TOON Format Specification

This repository contains the official specification for Token-Oriented Object Notation (TOON), a line-oriented, indentation-based encoding of the JSON data model. See github.com/toon-format/toon for an overview, rationale, and benchmarks.

Specification

→ Read the full specification (SPEC.md)

Version 4.2, Working Draft.

Serialization Example

Uniform arrays of objects collapse into a tabular form that declares the field list once (§9.3):

users[2]{id,name}:
  1,Ada
  2,Bob

{
  "users": [
    { "id": 1, "name": "Ada" },
    { "id": 2, "name": "Bob" }
  ]
}

That is one of TOON's four forms. The other three, with worked examples in examples/:

| Form | What it renders | Example | | ---- | --------------- | ------- | | Inline (§9.1) | Primitive arrays, on the header line itself | primitive-arrays.toon | | List (§9.2, §9.4) | Arrays that fit neither inline nor tabular form, one - item per element | mixed-arrays.toon | | Tabular (§9.3) | Arrays of uniform objects, as shown above | tabular-arrays.toon | | Keyed tabular (§9.5) | Objects whose values are uniform objects, as rows that carry their own key | keyed-tabular-objects.toon |

Within tabular form, a uniform nested-object column folds into the header as a nested field group (customer{name,country}) while rows stay flat – see nested-field-groups.toon.

See examples/README.md for the annotated index and SPEC.md Appendix A for more shapes.

Media Type & File Extension

Media type text/toon (provisional, UTF-8), file extension .toon. See §17 of SPEC.md.

Contributing

See CONTRIBUTING.md for how to propose changes and when an RFC is required. For implementation-specific questions or bugs, use the respective implementation repository.

Resources

• Glossary: CONTEXT.md – Canonical name for every concept, and the wordings to avoid
• Examples: examples/ – Working examples organized by feature
• Test Fixtures: tests/fixtures/ – Reference test fixtures
• Changelog: CHANGELOG.md – Version history and changes
• Versioning: VERSIONING.md – MAJOR.MINOR policy and compatibility guarantees
• Reference Implementation: github.com/toon-format/toon – TypeScript/JavaScript implementation
• Implementations: toonformat.dev/ecosystem/implementations – Official and community ports
• Benchmarks: Reference repo benchmarks/ – Token efficiency measurements and accuracy retrieval tests

License

MIT License © 2025-PRESENT Johann Schopplich