TOON Format Specification

This repository contains the official specification for Token-Oriented Object Notation (TOON), a compact, human-readable encoding of the JSON data model for LLM prompts. It provides a lossless serialization of the same objects, arrays, and primitives as JSON, but in a syntax that minimizes tokens and makes structure easy for models to follow.

📋 Specification

→ Read the full specification (SPEC.md)

• Version: 3.0 (2025-11-24)
• Status: Working Draft
• License: MIT

The specification includes complete grammar (ABNF), encoding rules, validation requirements, and conformance criteria.

What is TOON?

Important

For a high-level overview of TOON, its features and benefits, design goals, and comparisons to other formats, see the toon-format/toon repository.

Serialization Example

JSON

TOON

{ "context": { "task": "Our favorite hikes together", "location": "Boulder", "season": "spring_2025" }, "friends": ["ana", "luis", "sam"], "hikes": [ { "id": 1, "name": "Blue Lake Trail", "distanceKm": 7.5, "elevationGain": 320, "companion": "ana", "wasSunny": true }, { "id": 2, "name": "Ridge Overlook", "distanceKm": 9.2, "elevationGain": 540, "companion": "luis", "wasSunny": false }, { "id": 3, "name": "Wildflower Loop", "distanceKm": 5.1, "elevationGain": 180, "companion": "sam", "wasSunny": true } ] }

context: task: Our favorite hikes together location: Boulder season: spring_2025 friends[3]: ana,luis,sam hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}: 1,Blue Lake Trail,7.5,320,ana,true 2,Ridge Overlook,9.2,540,luis,false 3,Wildflower Loop,5.1,180,sam,true

Reference Implementation

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

Community Implementations

Official community-driven implementations are currently being developed at the github.com/toon-format organization.

Test Fixtures & Conformance

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:

1. Load JSON fixtures from tests/fixtures/encode/ and tests/fixtures/decode/.
2. Run each test case against your implementation.
3. Report results using the conformance badge system.

See tests/README.md for detailed fixture format and usage instructions.

Media Type & File Extension

TOON defines a provisional media type (see §18.2 of the specification):

• Media type: text/toon (provisional, pending IANA registration)
• File extension: .toon
• Charset: Always UTF-8

For HTTP usage:

Content-Type: text/toon

See the full IANA Considerations section for details.

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 follows semantic versioning. See VERSIONING.md for our versioning policy and compatibility guarantees.

Resources

• 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

License

MIT License © 2025-PRESENT Johann Schopplich