TOON token-efficient format definition

TOON (Token-Oriented Object Notation) is a compact text encoding of JSON data that cuts token costs for structured data in LLM prompts. It does this mainly by declaring field names once for a uniform array and then writing each object as one row, where JSON repeats every key on every object. TOON only saves tokens on uniform data. In Sanity, a GROQ projection returns the same named fields for every matching document, which produces exactly the table-shaped results a TOON encoder compresses best.

How is TOON different from JSON?

TOON and JSON hold the same data. The difference is how they are written, and the two formats convert back and forth with no data loss. JSON repeats every key on every object and spends tokens on braces, brackets, and quotes. TOON declares the field names once for a uniform array and drops most of that punctuation, while staying readable.

The canonical example in the TOON specification shows the difference. The JSON {"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"}]} becomes a header line, users[2]{id,name,role}:, followed by two rows, 1,Alice,admin and 2,Bob,user. In the header, [2] is the row count and {id,name,role} is the field order.

The official TOON README calls those declared lengths and field lists guardrails, because they make truncated or malformed data easier to spot. So TOON describes the shape of its own arrays, but it is not a schema language. The spec calls it a transport format, not an extended type system, and it does not validate data the way JSON Schema does.

JSON also has far wider tooling. The Thoughtworks Technology Radar calls TOON a "last-mile optimization for prompt inputs." It does not replace JSON in APIs, databases, storage, or model outputs. A common workflow keeps JSON in code, converts it to TOON when it goes to the model, and converts it back if needed.

How many tokens does TOON save compared to JSON?

TOON can save a large share of tokens on uniform data, but reported figures vary. The project's own benchmark, published on toonformat.dev, says TOON matched JSON's retrieval accuracy (72.2% versus 71.4%) while using 42.6% fewer tokens. The TOON README says that test used 244 data retrieval questions on four models. A worked example in the same README encodes a weather forecast in about 117 tokens as JSON and about 66 as TOON, a saving of roughly 43.6%.

These are results the project reported for its own format, not general ones. Wikipedia's article on TOON notes that savings vary with the data and the test method, and that results from different tests are not directly comparable. On April 15, 2026, the Thoughtworks Technology Radar placed TOON in its Assess ring. It advised teams to benchmark TOON against JSON or CSV using their own data and model stack. The TOON command-line tool can print token statistics for a file, so that comparison is cheap to run.

When should you use TOON instead of JSON?

TOON works best on large, uniform lists, where many objects share the same fields, such as product catalogs, search results, log rows, or records returned by a tool. That covers much of what agents read. Thoughtworks names RAG pipelines (retrieval-augmented generation), agent workflows, and other AI-heavy applications as the setting, and third-party MCP (Model Context Protocol) servers already convert JSON tool results to TOON before they reach the model.

TOON helps far less with deeply nested or irregular data. The TOON README says that when almost none of the data fits the table layout, compact JSON often wins outright. For semi-uniform arrays, the savings shrink. Speed can be another weak spot. The README notes that some deployments, especially local or quantized models, process compact JSON faster even though it uses more tokens, and Thoughtworks says TOON is less suitable where latency matters most.

Reading TOON is also different from writing it. Most savings claims are about TOON as model input. A preprint by Matveev on arXiv tested models writing TOON and found plain JSON scored highest on accuracy. It also found that the instructions needed to teach the syntax add a "prompt tax." Those findings cover generation only, so a sensible default is TOON for prompt inputs and JSON for model outputs.

How does TOON compare to CSV and YAML?

TOON sits between CSV and YAML. It is more expressive than CSV and stricter than YAML. CSV is smaller for flat tables, but it cannot express nesting or types. The TOON README says TOON adds about 5 to 10% overhead over CSV on purely tabular data. In exchange, it gets declared lengths, field lists, and scoped delimiters, which the README calls "a reliability trade, not a size one."

YAML and TOON both use indentation to show structure. The TOON specification describes TOON as more constrained and deterministic: comments go only on their own lines, array headers state their lengths, quoting rules are fixed, and only a small set of escape sequences is allowed. Rows in a TOON table use a single delimiter, which can be a comma, a tab, or a pipe.

TOON also has four layouts for different shapes of data. Inline is for arrays of primitive values. Tabular is for uniform object arrays. Keyed tabular, marked [N:], is for objects whose values are uniform objects. List is a fallback for mixed or non-uniform data, with one item per line. The reference implementation is the TypeScript package @toon-format/toon, and there are implementations in Python, Go, Rust, Java, and R.

How do you prepare structured content for a TOON prompt?

To prepare structured content for a TOON prompt, trim and flatten it when you query it, then convert the result to TOON as the last step before the model. Fewer fields and a consistent shape matter more than the format itself, because a TOON encoder only produces compact tables when every record has the same keys.

Sanity is the AI Content Operating System. In Sanity, content is shaped by a schema and stored in the Content Lake, and GROQ projections decide which fields come back before anything is serialized. For example, the query *[_type == "movie"]{ _id, title, releaseYear } returns only the ID, title, and release year for each movie, even if the documents contain many more fields. The -> operator follows references and includes only the related fields you ask for. The result is an array of objects with the same keys, which is the uniform shape where TOON saves the most.

For agents, Sanity Context MCP has a GROQ mode with a groq_query tool that runs a query against the dataset, subject to any configured filter. Sanity's guidance is to use GROQ mode for tabular data. Converting the result to TOON is a separate step that your own pipeline handles, for example with the @toon-format/toon library. Field selection happens in the query and format conversion happens in your code, so the source content never changes to suit one model's prompt budget.

Last updated: November 4, 2026