TOON vs JSON: what's the difference, and when to use each

JSON has been the default way to move structured data around for two decades. TOON is much newer, and it exists for one reason: language models charge you for every character of structure, and JSON has a lot of structure. So which should you use? The short answer is both — for different jobs. This is a side-by-side look at how they differ and where each one earns its place.

TOON vs JSON in one line

JSON is a general-purpose data format built for machines and humans to exchange data over APIs, files, and config. TOON (Token-Oriented Object Notation) is a compact encoding built for one specific moment: the point where structured data enters a large language model's prompt, where every token costs money and context space. TOON keeps JSON's information but throws away its repetition.

TOON vs JSON: the same data, side by side

Here is a small dataset in JSON — the shape almost every app produces, an array of objects with the same keys:

{
  "users": [
    { "id": 1, "name": "Ada", "role": "writer" },
    { "id": 2, "name": "Lin", "role": "developer" },
    { "id": 3, "name": "Sam", "role": "designer" }
  ]
}

Readable — but every key is repeated on every row, and the braces, quotes, colons, and commas add up.

And the same data in TOON, which declares the keys once in a header and then lists the rows underneath, like a lightweight table:

users[3]{id,name,role}:
  1,Ada,writer
  2,Lin,developer
  3,Sam,designer

The header carries the schema; the rows carry only data. Nothing is lost — the structure and types survive.

Both describe identical data. The difference is purely how much syntactic weight wraps it — and that weight is exactly what a model pays for.

How TOON and JSON compare

Where TOON's token savings over JSON come from

JSON's cost is repetition. In the example above, the keys id, name, and role are written out for every single row — three times here, fifty times in a 50-row table, thousands of times in a real payload. A human eye skips past it; a tokenizer does not. It counts every quote, brace, colon, and comma, and you are billed for all of them on every API call.

TOON writes the field names once in the header line and then streams nothing but values. The more rows you have, the more that one-time header pays off. We ran the actual numbers — same data, multiple formats, the real GPT-4o/5 tokenizer — in the token tax benchmark: pretty JSON cost 65% more tokens than TOON on a 50-row table, which translated to hundreds of dollars a month on a single repeated prompt.

The savings scale with repetition. A single small object? The difference is negligible — JSON is fine. A list of similar records? That is where the token tax is highest, and where TOON cuts the most.

Where TOON and JSON each win

Use JSON when…

• You are building or calling an API — JSON is the lingua franca and everything speaks it.
• You need a config file, a stored document, or data passed between services.
• The data is deeply nested or irregular, with no repeated structure to compress.
• You want a source of truth that any tool, in any language, can read without conversion.

Use TOON when…

• You are putting tables of data into an LLM prompt — users, products, rows from a spreadsheet, search results, logs.
• The same data is sent many times across a workflow or an agent loop, so token savings compound.
• You are close to a context-window limit and need to buy room for actual content.
• You want to cut input-token spend without losing structure or types.

Notice these lists barely overlap. That is the point: TOON does not compete with JSON for JSON's jobs. It optimizes the one narrow case JSON handles expensively.

Use JSON and TOON together

The practical pattern is to use both, in sequence. Keep JSON as your source of truth — that is what your database, API, and tools produce. Then, at the exact point where data goes into a prompt, convert it to TOON. When the model hands structured output back, convert it to JSON again so the rest of your stack can use it. JSON for storage and exchange, TOON for the prompt. Because TOON is loss-free for structured data, the round trip costs you nothing but tokens saved.

TOON vs JSON: the bottom line

JSON isn't going anywhere — it is the right default for almost everything and the format your systems should speak to each other in. TOON is a focused optimization for the age of LLMs: when you are paying per token to feed a model a table of data, TOON does the same job for a fraction of the cost. Use JSON to store and move data; use TOON to prompt with it.

New to the format? Start with what is TOON? for a plain-English tour, or how to convert JSON to TOON for the step-by-step. Want the hard numbers? See the token tax benchmark. Comparing config formats instead? Read YAML vs JSON.