TOON Format Specification

May 20, 2026 · View on GitHub

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: 3.2 (2026-05-20)
Status: Working Draft
License: MIT

The specification includes ABNF snippets, encoding rules, validation requirements, and conformance criteria.

Serialization Example

JSON	TOON
`{ "users": [ { "id": 1, "name": "Ada" }, { "id": 2, "name": "Linus" } ] }`	`users[2]{id,name}: 1,Ada 2,Linus`

See examples/ 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

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.

Versioning

The TOON specification uses MAJOR.MINOR versioning. See VERSIONING.md for the policy and compatibility guarantees.

Resources

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