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.0 (2026-07-22)
- Status: Working Draft
- License: MIT
The specification includes ABNF snippets, encoding rules, validation requirements, and conformance criteria.
Uniform arrays of objects collapse into a tabular form that declares the fields once (§9.3):
| JSON | TOON |
|---|---|
{
"users": [
{ "id": 1, "name": "Ada" },
{ "id": 2, "name": "Linus" }
]
} |
|
Uniform nested-object columns fold into the header as nested field groups; rows stay flat (§9.3):
| JSON | TOON |
|---|---|
{
"orders": [
{ "id": 1, "customer": { "name": "Ada", "country": "DK" }, "total": 99 },
{ "id": 2, "customer": { "name": "Bob", "country": "UK" }, "total": 149 }
]
} |
|
Objects whose values are uniform objects collapse into the keyed tabular form – the colon after the length marks the keyed header, and each entry row carries its own key (§9.5):
| JSON | TOON |
|---|---|
{
"environments": {
"production": { "region": "eu-central-1", "replicas": 6, "debug": false },
"staging": { "region": "eu-central-1", "replicas": 2, "debug": true }
}
} |
|
See examples/ and SPEC.md Appendix A for more shapes.
Media type text/toon (provisional, UTF-8), file extension .toon. See §17 of SPEC.md.
We welcome contributions to improve the specification! Please see CONTRIBUTING.md for:
- How to propose spec changes
- The RFC process for major changes
- Guidelines for submitting issues and pull requests
For implementation-specific questions or bugs, please refer to the respective implementation repository.
The TOON specification uses MAJOR.MINOR versioning. See VERSIONING.md for the policy and compatibility guarantees.
- Specification: SPEC.md - Formal specification with ABNF grammar snippets
- Examples: examples/ - Working examples organized by feature
- Test Fixtures: tests/fixtures/ - Reference test fixtures
- Changelog: CHANGELOG.md - Version history and changes
- Reference Implementation: github.com/toon-format/toon - TypeScript/JavaScript implementation
- Benchmarks: Reference repo benchmarks/ - Token efficiency measurements and accuracy retrieval tests
MIT License © 2025-PRESENT Johann Schopplich