This repository contains the official specification for Token-Oriented Object Notation (TOON), a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage.
→ Read the full specification (SPEC.md)
- Version: 2.0 (2025-11-10)
- Status: Working Draft
- License: MIT
The specification includes complete grammar (ABNF), encoding rules, validation requirements, and conformance criteria.
Token-Oriented Object Notation is a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage. It's intended for LLM input, not output.
TOON's sweet spot is uniform arrays of objects – multiple fields per row, same structure across items. It borrows YAML's indentation-based structure for nested objects and CSV's tabular format for uniform data rows, then optimizes both for token efficiency in LLM contexts. For deeply nested or non-uniform data, JSON may be more efficient.
Key Features:
- 💸 Token-efficient: typically 30–60% fewer tokens than JSON
- 🤿 LLM-friendly guardrails: explicit lengths and fields enable validation
- 🍱 Minimal syntax: removes redundant punctuation (braces, brackets, most quotes)
- 📐 Indentation-based structure: like YAML, uses whitespace instead of braces
- 🧺 Tabular arrays: declare keys once, stream data as rows
JSON:
{
"users": [
{ "id": 1, "name": "Alice", "role": "admin" },
{ "id": 2, "name": "Bob", "role": "user" }
]
}TOON:
users[2]{id,name,role}:
1,Alice,admin
2,Bob,user
The reference implementation in TypeScript/JavaScript is maintained at: github.com/toon-format/toon
The reference implementation includes:
- Complete encoder and decoder
- CLI tools for JSON ↔ TOON conversion
- Performance benchmarks
Official community-driven implementations are currently being developed at the github.com/toon-format organization.
The tests/fixtures/ directory contains language-agnostic JSON test fixtures for validating TOON implementations. Each fixture file contains test cases with input/output pairs covering all specification requirements.
What's included:
- Encoding tests: JSON → TOON conversion
- Decoding tests: TOON → JSON parsing
- Error cases: Validation and strict mode checks
- Edge cases: All corner cases from the specification
For implementers:
- Load JSON fixtures from
tests/fixtures/encode/andtests/fixtures/decode/. - Run each test case against your implementation.
- Report results using the conformance badge system.
See tests/README.md for detailed fixture format and usage instructions.
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 follows semantic versioning. See VERSIONING.md for our versioning policy and compatibility guarantees.
- Specification: SPEC.md - Complete formal specification with ABNF grammar
- Examples: examples/ - Working examples organized by feature
- Test Fixtures: tests/fixtures/ - Comprehensive test suite
- 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
