TOON Format Specification

February 23, 2026 · View on GitHub

SPEC v3.0 Tests License: MIT

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

License

MIT License © 2025-PRESENT Johann Schopplich