JSON Toolkit

TOON Format Guide: Shrink JSON Before Feeding It to an LLM

Bottom line: Feeding a uniform array to a large language model in JSON burns tokens on repeated key names and brackets. TOON declares the structure once with indented objects and tabular arrays, then streams row data — official benchmarks show ~40% fewer tokens and higher parse accuracy. This guide covers the syntax, when the savings apply, when not to convert, and how to wire up encode and decode.

Beginner~6 min readPublished 2026-11-10Updated 2026-11-10
TOON tabular array syntax: field header declared once, data rows streamed line by line

JSON's syntax overhead is irrelevant for machine-to-machine transfer, but on the token-billed input side of an LLM it is real money: the same uniform array repeats its key names dozens of times, and every bracket and quote takes a share. TOON does not invent a new data model — it rewrites the JSON data model in a cheaper notation.

What TOON Is: Another Encoding of JSON, Not a Competitor

TOON (Token-Oriented Object Notation) is an open format introduced in 2025, and the official positioning fits in one sentence: a compact, lossless, human-readable encoding of the JSON data model. It adds no new types — objects, arrays, strings, numbers, booleans and null map one-to-one to JSON, and decode(encode(x)) strictly equals the original data (non-JSON types like Date or NaN must be normalized first). The round trip is lossless and deterministic: the same input always produces the same output, which matters when you need reproducible prompt construction.

Because it encodes exactly the JSON data model, the correct way to use TOON is as a boundary format: your application keeps using JSON internally, converts to TOON once just before placing data into a prompt, and converts back when the model responds. The official docs call it a "translation layer". The conventional file extension is .toon; for HTTP transport the provisional media type is text/toon, UTF-8.

One search-noise warning: do not confuse it with Toon Shaders in computer graphics. They share nothing but the word.

Why JSON Is Especially Expensive on the LLM Input Side

Take an order list, a user roster or a log digest written as a JSON array. The tokens go to three places:

  1. Repeated key names. Fifty order records write "id", "amount" and "status" fifty times each. Double the data, double the key overhead.
  2. Structural punctuation. Braces, brackets, colons and commas all consume tokens, and nesting packs them denser.
  3. Quotes. Almost every key and string value is wrapped in double quotes.

Together these mean: API cost billed per token rises directly; longer inputs hit the context-window ceiling sooner; and on very long inputs the model drops or misassigns fields more often. The benchmark on the official TOON homepage: across a mixed-structure test set and four models, ~40% fewer tokens with parse accuracy rising from JSON's 70% to TOON's 74%. Savings and accuracy are not a trade-off here, because the tighter structure makes boundaries easier for the model to see.

Syntax: Indented Objects + Tabular Arrays

The same weather-forecast data in three forms. JSON, about 117 tokens:

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

TOON, about 66 tokens:

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

Three forms cover everything, and the serializer picks them from the data's shape:

Form Fits JSON equivalent
Indented object Nested objects { "location": { ... } }, indentation replaces braces
Inline array Arrays of primitives ["frost","wind"], [2] declares the length
Tabular array Uniform object arrays Field names appear once in the header {day,temp{min,max},...}; each row is comma-separated values only

Uniform nested objects (temp{min,max}) fold into the header as a nested field group while rows stay flat. Quoting is minimal: strings are quoted only when they contain delimiters, special characters, or would be misread as numbers — one reason it beats "compact JSON" on token count. The key difference from YAML is TOON's explicit length declarations and field headers, which machines can validate; the difference from CSV is that it keeps nesting and types.

[N] and {fields}: Structural Guardrails for the Model

[3] and {day,...} are not just token savings — they are a validatable contract handed to the model:

  • Array length lets the model answer "how many records are in the dataset" directly, and exposes truncation immediately when row counts do not match.
  • Field header declares names once; the model aligns values by position instead of re-guessing key mappings on every line.

This is prevention, the opposite of after-the-fact rescue. A JSON repairer (see the repair pipeline) salvages data after the model emits broken JSON; TOON's length and field declarations lower the odds of broken data on the input side. Do both and the mid-pipeline parse failure rate comes down.

When Not to Use TOON

The official "When Not to Use TOON" section is refreshingly blunt. Four scenarios, worth copying verbatim:

Scenario Why not Better option
Deeply nested, non-uniform structures Tabular eligibility ≈ 0%; compact JSON often wins Compact JSON
Semi-uniform arrays Ragged fields, savings shrink to nearly nothing Keep your JSON pipeline
Purely tabular data TOON adds 5–10% overhead over CSV CSV
Latency-sensitive (local/quantized models) Fewer tokens ≠ faster inference Measure TTFT first

Semi-uniform is judged by tabular eligibility: officially, at 40–60% eligibility the savings are already marginal. Format migration carries real cost — parsers, validators, downstream scripts all change — so if the gain is under ten percent, do not bother.

Wiring It Up: encode / decode and the CLI

The official TypeScript library, both directions:

npm install @toon-format/toon
# Batch conversion also works through the CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // strictly equals the original data

Python, Go, Rust and .NET implementations exist; check the implementation list in the official spec repository before adopting one, and confirm it covers the syntax features you use. Before production, run a round-trip assertion: decode(encode(original)) must deep-equal the original, otherwise the implementation or the data has a problem.

How It Fits Your Existing JSON Toolchain

TOON changes nothing in your JSON pipeline; it adds one boundary conversion. Suggested order:

  1. Make sure the JSON itself is clean first. Broken JSON converts to broken TOON. Syntax validation and repair are covered in the JSON Repair Guide.
  2. Check the data shape. Are the objects in the array field-complete? Normalize first, or conclude the conversion is not worth it.
  3. Convert and spot-check. After conversion, compare one data row against the original JSON to confirm field alignment has not drifted.
  4. Estimate the benefit. For uniform lists, the line-by-line thinking in the JSONL file handbook applies to streaming conversion; for how size relates to cost, the real relationship between JSON minify and gzip makes the same point: measure first, convert second.

Will TOON replace JSON?

No. TOON encodes the JSON data model; its place is the prompt boundary, while storage and exchange between programs stay JSON. Use TOON for the "feed the model" segment and leave the rest of the chain untouched.

How does TOON relate to YAML and CSV?

Objects look like YAML (indentation instead of braces); uniform arrays look like CSV (header declared once, rows streamed). But TOON has explicit length declarations that YAML lacks, and nesting and type preservation that CSV lacks — it sits between the two, with machine-validatable guardrails added.

Does converting TOON to JSON lose data?

No: objects, arrays, strings, numbers, booleans and null all map one-to-one, and decode(encode(x)) is strictly equal. The only caveat is normalizing non-JSON types like Date and NaN first, otherwise equality holds only after the round trip.

How do I verify the converted TOON is correct?

Two checks: a round-trip assertion (encode then decode, deep-equal to the original), and a manual spot check of the header — the number in [N] must equal the row count, and the fields in {fields} must align one-to-one with the comma-separated values in each row. On the model side, you can also ask it to report the array length before answering.