📚 Toon Format Documentation

Complete guide to the Toon format - a compact, human-readable serialization format that reduces token usage when sending JSON data to LLMs. Learn syntax, examples, and best practices.

❓ What is Toon?

Toon (Token-Oriented Object Notation) is a compact, human-readable data serialization format designed to reduce the number of tokens used when sending structured JSON data to large language models. It provides a more token-efficient alternative to JSON while remaining easy for humans to read.

The format was created to address the token overhead of JSON in AI workloads such as RAG pipelines, agent tool calls, and LLM context windows, where repeated object keys and punctuation add up to significant, avoidable token cost. According to the TOON format's published benchmarks, TOON uses roughly 42.6% fewer tokens than equivalent JSON while achieving comparable or better LLM retrieval accuracy (72.2% vs. JSON's 71.4% in their tests). See the TOON spec and reference implementation for details.

🔤 Basic Syntax

Key-Value Pairs

The most basic Toon syntax uses key-value pairs separated by colons: 

name: John Doe
age: 30
city: New York

Nested Objects

Objects are represented by indentation, with no braces needed: 

location:
    city: Berlin
    country: DE

Arrays of Primitives

Arrays of primitive values are written inline with a [N]: count marker followed by comma-separated values: 

tags[3]: red,green,blue

Arrays of Uniform Objects (Tabular Form)

This is TOON's key space-saving feature. When an array contains objects that share the same fields, the field names are declared once in a header line, and each row is then just comma-separated values with no repeated keys - avoiding JSON's per-object key repetition: 

forecast[2]{day,temp,condition}:
    Mon,-2,snow
    Tue,1,cloudy

📊 Data Types

🔤 Strings

Text values, optionally quoted 

name: Ada Lovelace
role: "Software Engineer"
notes: "Wrote the first algorithm"

🔢 Numbers

Integers and decimals 

age: 30
temperature: -2.5
tokenCount: 1024

✅ Booleans

True or false values 

isActive: true
isArchived: false
hasError: false

📋 Arrays

Inline count marker with comma-separated values 

tags[3]: red,green,blue
scores[3]: 167,219,342
models[2]: gpt-4,claude

📖 Examples

Simple Record

user:
    name: Jane Smith
    role: Engineer
    active: true
    location:
        city: Berlin
        country: DE
    tags[2]: backend,ai

Array of Objects (Tabular Form)

This is where TOON saves the most tokens versus JSON: field names are declared once instead of being repeated for every object in the array. 

forecast[3]{day,temp,condition}:
    Mon,-2,snow
    Tue,1,cloudy
    Wed,4,sunny

🤔 Rationale

Lower Token Usage for LLM Prompts

Toon was created to cut the token cost of sending structured JSON data to large language models. According to the TOON format's published benchmarks, TOON uses approximately 42.6% fewer tokens than equivalent JSON, which directly reduces prompt costs and frees up context window space in RAG pipelines, agent tool calls, and other AI workloads.

Human Readability

Toon prioritizes human readability alongside token efficiency. Unlike JSON, which can become dense and repetitive with nested structures and arrays of objects, Toon uses indentation and a tabular header syntax for arrays to stay easy to scan while avoiding repeated keys.

Comparable or Better LLM Retrieval Accuracy

Reducing tokens is only useful if the model can still work with the data accurately. In the TOON format's published benchmarks, LLMs retrieving data from TOON-encoded input matched or slightly outperformed JSON (72.2% vs. JSON's 71.4% accuracy), suggesting the format's structure doesn't come at the cost of comprehension.

Data Integrity

Despite its more compact syntax, Toon maintains full data fidelity. All data types supported by JSON are also supported by Toon, ensuring no information is lost during conversion between formats.

🔄 Comparison with JSON

Feature JSON Toon
Readability ❌ Verbose with brackets ✅ Clean, minimal syntax
LLM Token Usage ❌ Baseline (more tokens) ✅ ~42.6% fewer tokens*
Learning Curve ⚠️ Requires syntax knowledge ✅ Simple, intuitive syntax
Tool Support ✅ Extensive ⚠️ Growing ecosystem
Standardization ✅ RFC 8259 ⚠️ Emerging standard

* Per the TOON format's published benchmarks (see the TOON spec repository), which also report comparable-or-better LLM retrieval accuracy versus JSON (72.2% vs. 71.4%).

🚀 Getting Started

Ready to start using Toon format? You can begin by converting your existing JSON files using our free online converter above, or download the Toon format specification from our GitHub repository.

Try the Converter View on GitHub