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.
→ Read the full specification (SPEC.md)
Version 4.1, Working Draft.
Uniform arrays of objects collapse into a tabular form that declares the field list once (§9.3):
| TOON | JSON |
|---|---|
|
{
"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 text/toon (provisional, UTF-8), file extension .toon. See §17 of SPEC.md.
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.
- 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
MIT License © 2025-PRESENT Johann Schopplich
