What is TOON? The format explained

TOON — Token-Oriented Object Notation — is a text format that encodes the same data model as JSON, using fewer tokens when that data goes into a language model’s prompt. It is not a new data model, not a binary format and not a replacement for JSON in APIs or storage. It is a serialisation you convert to immediately before a prompt and convert back from afterwards.

The current specification is version 4.1. There is a reference implementation in TypeScript and community ports for Python, Rust, Go, Java, Swift and .NET.

The syntax in three examples

Objects use indentation instead of braces, like YAML:

status: ok
page: 1
server:
  host: api.example.com
  port: 443

Arrays declare their length, so a reader — human or model — knows how many items to expect without counting:

tags[3]: beta,eu,internal

Uniform record arrays get the form that gives the format its purpose. The field names are declared once in braces, and the records follow as rows:

users[3]{id,name,role}:
  1001,ada,admin
  1002,alan,member
  1003,grace,admin

The same data as JSON repeats id, name and role three times each:

[
  {"id":1001,"name":"ada","role":"admin"},
  {"id":1002,"name":"alan","role":"member"},
  {"id":1003,"name":"grace","role":"admin"}
]

That difference is the entire saving. Everything else in the format is machinery to make it round-trip safely.

What it preserves

TOON encodes the JSON data model exactly: objects, arrays, strings, numbers, booleans and null. A value that survives JSON.parse(JSON.stringify(x)) survives a TOON round trip, and one that does not, does not.

Negative zero is the neat illustration. JSON.stringify(-0) produces "0", so JSON itself loses the sign — and TOON, encoding the same model, loses it in exactly the same place. A TOON encoder cannot preserve more than JSON does, and that is by design rather than by oversight.

What it costs

Three things, and the third is the one that surprises people.

It only helps on the right shape. The tabular form needs a uniform array of records whose fields are all primitives. Nested data has nothing to compress; a single array field inside the records disables the tabular form completely. Details and measurements.

It is another dependency in the path. Encode before the call, decode after, handle failures on both sides. Modest, but not nothing.

The model has to know the format. JSON needs no explanation — every model has seen enormous quantities of it. TOON is newer and less represented in training data, so prompts often carry a short syntax explanation, and those tokens count against the saving. On large payloads sent at volume they disappear into the noise; on small, occasional prompts they can exceed the entire benefit.

When it is worth it

Roughly: large uniform record arrays, sent often, to a model that handles the format well.

• Good fit — a few hundred rows of tabular data in every call, all primitive fields, high call volume.
• Poor fit — a nested configuration object, a one-off prompt, or records carrying arrays.
• Better served by CSV — a flat table with no envelope and no type ambiguity. CSV spends nothing on structure and comes out smaller still.

Trying it

Paste a payload into the converter. It encodes it, counts the tokens for both formats with the real tokenizer, and states which format is cheapest for that specific shape — including the cases where the answer is “not TOON”.

The specification lives at github.com/toon-format/spec.