Skip to content

README.md

Latest commit

 

History

History
152 lines (116 loc) · 8.02 KB

README.md

File metadata and controls

152 lines (116 loc) · 8.02 KB

TOON Examples

This directory contains example TOON files demonstrating various features of the format. Examples are organized into three categories:

Valid Examples

Complete, valid TOON files demonstrating core features:

Objects

  • valid/objects.toon - Simple flat object with primitive values

    • Demonstrates basic key-value pairs
    • Shows multiple data types: string, number, boolean, null
    • Spec: §8 Objects

  • valid/nested-objects.toon - Multi-level nested objects

    • Demonstrates indentation-based nesting (2 spaces per level)
    • Shows how objects can contain other objects
    • Spec: §8 Objects, §12 Indentation

Arrays

  • valid/primitive-arrays.toon - Inline primitive arrays

    • Demonstrates compact inline format [N]: item1,item2,item3
    • Shows empty arrays [0]:
    • Multiple arrays in one document
    • Spec: §9.1 Primitive Arrays

  • valid/tabular-array.toon - Tabular array format (comma delimiter)

    • Demonstrates the most token-efficient format for uniform data
    • Header declares fields once: {field1,field2,...}
    • Rows contain only data values
    • Spec: §9.3 Tabular Arrays

  • valid/mixed-array.toon - Mixed-type array (list format)

    • Demonstrates list format with - prefix
    • Shows arrays containing different types (number, object, string)
    • Useful when items don't have uniform structure
    • Spec: §9.4 Mixed Arrays

Delimiters

  • valid/pipe-delimiter.toon - Pipe delimiter (|)

    • Shows alternative delimiter for tabular arrays
    • Delimiter marker appears in both header [N|] and field list {field|...}
    • Useful when data contains commas
    • Spec: §11 Delimiters

  • valid/tab-delimiter.toon - Tab delimiter (\t)

    • Demonstrates tab-separated tabular format
    • Tab character appears in both header and between fields
    • Useful for TSV-like data
    • Spec: §11 Delimiters

  • valid/delimiter-scoping.toon - Document vs active delimiter

    • Shows that tabular row cells split only on the active delimiter
    • Shows that object field values still follow document delimiter quoting rules
    • Spec: §11.1 Delimiters (Encoding Rules)

Key Folding and Path Expansion (v1.5+)

Regenerate any of these examples via the reference CLI, e.g. npx @toon-format/cli --encode --keyFolding safe examples/valid/key-folding-basic.json --output examples/valid/key-folding-basic.toon.

  • valid/key-folding-basic.toon - Basic dotted-key notation

    • Demonstrates how keyFolding="safe" only folds chains of single-key objects (e.g. server.host: localhost)
    • Notes that siblings such as database.connection.username need their own wrapper objects in the JSON source
    • Generated directly from valid/key-folding-basic.json using the CLI encoder
    • Decode tip: use expandPaths="safe" to reconstruct the nested JSON structure
    • Spec: §13.4 Key Folding and Path Expansion

  • valid/key-folding-with-array.toon - Dotted keys with arrays

    • Shows folding combined with inline arrays: data.meta.items[3]: widget,gadget,tool
    • Adds folded scalar stats.meta.count: 3 plus folded array user.preferences.tags[2]: …
    • Shows that arrays stop the folding chain yet remain inline when the parent chain qualifies
    • Decode tip: use expandPaths="safe" to reconstruct the nested JSON structure
    • Spec: §13.4 Key Folding

  • valid/key-folding-mixed.toon - Mixed folding strategies

    • Combines standard nested objects (app, server) with folded keys (database.connection.url, feature.flags.beta)
    • Shows the encoder mixing folded and non-folded sections within the same document
    • Useful when only some branches meet the single-key-chain requirement
    • Decode tip: use expandPaths="safe" to reconstruct the nested JSON structure
    • Spec: §13.4 Key Folding

  • valid/path-expansion-merge.toon - Deep merge behavior

    • Demonstrates how overlapping dotted keys merge during expansion
    • Shows user.profile.name: Ada + user.settings.theme: dark → nested object with both branches
    • Decoder option expandPaths="safe" reconstructs nested structure
    • Spec: §13.4 Path Expansion

Invalid Examples

Examples that intentionally violate TOON syntax rules:

  • invalid/length-mismatch.toon - Array length mismatch

    • Declares [3] but provides only 2 items
    • Should fail validation in strict mode
    • Spec: §14.1 Strict Mode (Array Count & Width)

  • invalid/missing-colon.toon - Missing colon after key

    • Keys must be followed by :; when a value appears on the same line, the format MUST be : (colon + single space)
    • Demonstrates common syntax error
    • Spec: §8 Objects, §14.2 Syntax Errors

  • invalid/path-expansion-conflict-strict.toon - Path expansion conflict (v1.5+)

    • First line creates nested path user.profile.name, second line tries to assign primitive to user.profile
    • Fails when decoded with expandPaths="safe" and strict=true (default)
    • With strict=false, applies LWW conflict resolution (later value wins)
    • Spec: §13.4 Path Expansion, §14.5 Conflicts

  • valid/key-folding-non-identifier.toon - Non-identifier segments (v1.5+)

    • Contains dotted keys with segments like first-name with hyphens (not valid IdentifierSegments)
    • Keys are quoted (hyphens are not allowed in unquoted keys)
    • These remain as literal dotted keys when expandPaths="safe" is used
    • Spec: §13.4 Safe Mode Requirements, §1.9 IdentifierSegment, §7.3 Key Encoding

  • invalid/delimiter-mismatch.toon - Header delimiter mismatch

    • Declares pipe delimiter in brackets ([N|]) but uses comma-separated fields ({a,b})
    • MUST error in strict mode
    • Spec: §6 Header Syntax (delimiter equality requirement)

Conversions

Side-by-side JSON ↔ TOON examples showing equivalent representations:

  • conversions/users.json + conversions/users.toon

    • Same tabular data in both formats
    • Shows token reduction achieved by TOON (≈30-60% for tabular data)
    • Demonstrates the primary use case: uniform arrays of objects

  • conversions/config.json + conversions/config.toon (v1.5+)

    • Deeply nested configuration data (server, database, logging settings)
    • Regenerated with keyFolding="safe"; because most objects are multi-key, folding halts quickly and the output stays primarily nested (the stop condition)
    • Shows ≈40-50% token reduction versus the JSON source while remaining spec-compliant
    • Highlights how safe folding behaves when little or no folding is permitted

  • conversions/api-response.json + conversions/api-response.toon (v1.5+)

    • API response with nested data and metadata
    • Regenerated with keyFolding="safe"; multi-sibling branches like data and meta stay fully nested instead of becoming dotted keys (stop condition on display)
    • Shows practical use case for serializing API responses while preserving deterministic structure
    • expandPaths="safe" is not required for this file (no folded keys)

Using These Examples

These examples are useful for:

  1. Learning TOON syntax - Study working examples to understand the format.
  2. Testing implementations - Verify your parser/encoder handles these cases.
  3. Documentation - Reference examples when explaining TOON features.
  4. Debugging - Compare your output with these known-good examples.

For comprehensive test coverage, see the tests/ directory which contains language-agnostic JSON test fixtures covering all spec requirements.