TOON: A Token-Saving Serialization Format for LLM Prompts
🎒 Token-Oriented Object Notation (TOON) – compact, human-readable serialization of JSON data for LLM prompts. TypeScript SDK, CLI, benchmarks.
At a glance
- What is it?
- TOON is a lossless encoding of JSON that cuts token counts by over 40% for uniform data, using YAML-like indentation and CSV-like tables. It targets developers who pay for LLM tokens, but it is not the right choice for deeply nested or purely tabular data.
- Who is it for?
- Adopt TOON if your LLM workloads are dominated by arrays of uniform objects, where token costs are high and you can tolerate a small reliability overhead over raw CSV. Skip it if your data is deeply nested, non-uniform, or purely tabular, or if your latency budget is tight and you run local models.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Problem TOON Solves
LLM APIs charge per token, and JSON spends a large share of those tokens on structural punctuation: braces, quotes, commas, and repeated field names. TOON is a serialization format that encodes the same JSON data model into a more compact text form, aiming to reduce token consumption while preserving the ability of models to parse and validate the content accurately. The target user is a developer who already has JSON data, typically from an API or database, and needs to insert that data into a prompt for a language model. The README frames TOON as a translation layer: keep JSON in your program, encode it to TOON only for LLM input, and decode it back losslessly. Its sweet spot is arrays of objects that share the same fields, where the field names can be declared once instead of repeated for every row.
The Four Forms: How TOON Achieves Compactness
TOON does not use a single syntax. It picks from four forms based on the shape of the data, which is a key mechanism to understand. The inline form handles primitive arrays by placing the values on the same line as the key, as in `alerts[2]: frost,wind`. The tabular form is for arrays of uniform objects: the header line declares the field list once, such as `forecast[3]{day,temp{min,max},condition,rainChance}:`, and then each row is a comma-separated list of values, one per element. The keyed tabular form extends this to objects whose values are uniform objects, like a map of environments, where each row starts with its own key, shown as `production: eu-central-1,6,false`. Finally, the list form is the fallback for anything that does not fit, using one `- ` item per element. This design means the format is not a single grammar but a set of heuristics that choose the most compact representation automatically.
Guardrails for LLM Output: Declared Lengths and Field Lists
One of TOON's stated advantages is that it gives models explicit structural constraints. The `[N]` notation declares how many rows are expected, and the `{fields}` notation declares how wide each row is. The README claims this means truncated or malformed output cannot slip through silently, because a model that outputs fewer rows or missing fields is visibly wrong. This is a meaningful difference from plain JSON, where a truncated array can look like a valid but shorter list. For a developer using TOON to generate structured output from a model, this could reduce parsing errors, though the README does not provide a parsing algorithm or a validation library. The guardrail is a property of the format itself, not of a specific parser, so you would need to check the spec for how to validate conformance in your own code.
Token Savings: The Benchmark Claims
The README presents a concrete example: a weather forecast in JSON is approximately 117 tokens, while the same data in TOON is about 66 tokens, a saving of 43.6%. The README also states that TOON matches JSON's retrieval accuracy while using 42.6% fewer tokens, though the exact benchmark methodology is not detailed in the provided material. The benchmarks are split into two tracks: a mixed-structure track that includes nested and semi-uniform data, comparing TOON against JSON, YAML, and XML, and a flat-only track where CSV is included as a fair competitor. This split matters because CSV cannot represent nested structures without lossy flattening, so the comparison is designed to be fair. The token estimates come from the CLI's `--stats` flag, which prints the TOON output and the estimated token counts, but the README does not specify which tokenizer is used for these estimates. You should treat the 42.6% figure as an indicative result from an unknown tokenizer, not a universal guarantee.
Installation and Getting Started
The README shows a quick no-install path: `cat data.json | npx @toon-format/cli --stats`. This command reads JSON from stdin and prints the TOON representation along with token savings. For a more permanent setup, the SDK is published on npm as `@toon-format/toon`, and the CLI is `@toon-format/cli`. The repository is written in TypeScript, and the latest releases include v4.1.1, v4.1.0, and v4.0.0. The README does not provide explicit usage examples for the SDK beyond the CLI, but the presence of a TypeScript SDK implies you can call functions to encode and decode data programmatically. The spec is maintained in a separate repository at `toon-format/spec`, and the README links to a full specification document. The media type and file extension are mentioned in the table of contents but not detailed in the provided text, so you would need to consult the spec or the website toonformat.dev for that information.
When Not to Use TOON
The README is refreshingly honest about the format's limits. It explicitly says that for deeply nested or non-uniform structures, where tabular eligibility is close to 0%, compact JSON often wins outright. For semi-uniform arrays with 40 to 60 percent eligibility, the savings shrink, and the README advises staying on JSON if your pipeline already speaks it. For purely tabular data, CSV is smaller; TOON's 5 to 10 percent overhead buys declared lengths, field lists, and delimiter scoping, which the README calls a reliability trade, not a size one. Finally, latency is a factor: some deployments, notably local or quantized models, process compact JSON faster despite a higher token count. The README tells you to measure time-to-first-token and total time on your own setup, because token savings do not always translate to faster responses.
Alternatives and Ecosystem
The obvious alternative is YAML, which also uses indentation and is human-readable, but YAML is not optimized for token count and has a more complex syntax with anchors and type coercion. Another alternative is CSV, but CSV cannot represent nested objects without flattening, which loses structure. TOON sits between them: it uses YAML-like indentation for nesting and CSV-like rows for uniform data. The README mentions a multi-language ecosystem with official implementations and dozens of community ports, all targeting a single spec with a shared conformance test suite. This is an advantage over a bespoke format, because conformance tests give you some confidence that different implementations will produce the same output. However, the README also notes that the format is stable but still an idea in progress, and nothing is set in stone, so the ecosystem may shift as the spec evolves.
Maintenance and License
The project is licensed under MIT, which permits commercial use, modification, and redistribution with attribution. The repository is not archived, and the last push was in September 2026, with the most recent release being v4.1.1 from August 2026. The version history shows active development, with three releases in a short span, indicating that breaking changes can occur, as seen in the jump to v4.0.0. The README says the format is stable, but it also invites contribution to the spec, so you should expect possible revisions. The maintenance cost for you is low if you use the CLI, but if you integrate the SDK, you will need to track updates and potentially adjust your code when the spec changes. The conformance test suite is a positive sign for cross-implementation consistency, but it does not guarantee that all ports are equally maintained. Check the spec repository for the current version and any migration notes before upgrading.
Editorial conclusion
Adopt TOON if your LLM workloads are dominated by arrays of uniform objects, where token costs are high and you can tolerate a small reliability overhead over raw CSV. Skip it if your data is deeply nested, non-uniform, or purely tabular, or if your latency budget is tight and you run local models. Before adopting, verify that your data's tabular eligibility is high (above 60%), measure token savings on your own prompts, and test retrieval accuracy on your specific model, since the README's accuracy claims come from an unspecified benchmark track. Also confirm that your pipeline can handle the additional conversion step and that your model's tokenizer behaves as estimated. The spec is at v4.1 and the SDK is at v4.1.1, so pin your dependency to a specific version and watch for changes, as the format is still evolving.
Community notes