Direct Answer
TOON (Token-Oriented Object Notation) is a compact text encoding of the JSON data model for LLM input. Its main advantage appears when data contains uniform arrays of objects, because field names can be declared once and rows can carry only values.
TOON does not guarantee a fixed token reduction, lower latency, higher accuracy, or compatibility with every model. The current TOON v4.1 specification is a Working Draft. Use TOON as a measured translation layer at an LLM boundary, while keeping JSON or typed objects as the application source of truth.
What TOON Encodes
TOON v4.1 represents the same six JSON value categories: object, array, string, number, boolean, and null. It uses indentation, explicit array lengths, scoped delimiters, and minimal quoting.
Example JSON:
{
"users": [
{"id": 1, "name": "Ada", "role": "admin"},
{"id": 2, "name": "Bob", "role": "user"}
]
}
Equivalent TOON:
users[2]{id,name,role}:
1,Ada,admin
2,Bob,user
The reduction comes from removing repeated keys and punctuation. If the data has no repeated structure, that advantage can disappear.
The Four Data Shapes
The v4.1 specification chooses among four forms according to data shape:
| Form | Suitable data | Example |
|---|---|---|
| Inline | Primitive array | tags[3]: api,go,ai |
| List | Mixed or non-uniform array | One - item per element |
| Tabular | Uniform object array | users[2]{id,name}: |
| Keyed tabular | Object whose values share one shape | Keys plus shared fields |
Objects use indented key-value lines. Strings are quoted only when required by the grammar, including ambiguous literals, active delimiters, leading/trailing whitespace, and certain special characters.
Explicit lengths and field lists can help a strict decoder detect missing rows or columns. They do not prove that the values are factually correct.
When TOON Is a Good Candidate
Evaluate TOON when:
- a prompt contains large, uniform arrays of records;
- repeated JSON keys dominate the payload;
- the receiving model has demonstrated TOON comprehension;
- your application can encode and strictly decode with a pinned implementation;
- the data crosses an internal LLM boundary rather than a public API contract;
- lower token count would materially affect capacity or cost.
Examples include selected analytics rows, product records, event summaries, or read-only tool results with a stable shape.
Use JSON, compact JSON, CSV, or another contract when:
- data is deeply nested, sparse, or non-uniform;
- the payload is so small that format instructions dominate;
- a provider's constrained JSON output is reliable for the schema;
- external systems already require
application/json; - model output must integrate with broad existing tooling;
- the team cannot operate a versioned codec and conformance suite.
For a flat table, CSV may be smaller. For mixed application objects, compact JSON can be smaller and more interoperable.
Why a Universal Savings Percentage Is Wrong
Token savings depend on:
payload shape
+ serializer options
+ JSON baseline (pretty or compact)
+ tokenizer and vocabulary
+ language and values
+ TOON instructions and examples
+ generated-output errors
+ repair and retry turns
Character count is not token count. The same text can tokenize differently across encodings, and punctuation may merge with adjacent text. Do not estimate production usage with “four characters per token.”
The official project publishes benchmark results for its own corpus and models. Those results are useful evidence for the tested setup, not a service-level promise.
Two independent 2026 studies expose the boundary:
- A TOON generation comparison found that prompt overhead and repair cycles can reduce the advantage on short or complex outputs; plain JSON had stronger one-shot and final accuracy in that experiment, while constrained JSON used fewer tokens on some simple cases.
- An agentic tool-use benchmark tested four benchmarks and five open-weight models. It reported TOON reductions up to 18% with an accuracy cost up to 9 percentage points in its aggregate settings, plus multi-turn parsing failures that could cascade.
Neither paper proves that TOON is bad. Together they show why input compression, output generation, and end-to-end Agent success must be measured separately.
Input and Output Are Different Decisions
Using TOON for trusted application-generated input is easier than asking a model to generate TOON.
Input Translation
typed application data
-> JSON-compatible value
-> pinned TOON encoder
-> model context
The application controls serialization. Measure comprehension against the same data in compact JSON.
Model-Generated Output
model output
-> strict TOON decoder
-> schema and semantic validation
-> retry or reject
Generation adds parse and repair risk. A constrained JSON API may provide a stronger output contract. Compare first-pass validity, semantic accuracy, total tokens including repair, and tail latency.
Tool protocols such as function calling and MCP commonly use JSON-shaped schemas and wire messages. Replacing their external wire format is different from compacting a bounded data block inside model context. Do not call TOON a protocol upgrade.
Version and Round-Trip Contracts
Record:
{
"format": "toon",
"spec_revision": "4.1",
"implementation": "github.com/toon-format/toon-go",
"implementation_version": "v0.1.0",
"options": {
"indent": 2,
"delimiter": "comma",
"strict_decode": true
},
"source_schema": "records-v3",
"tokenizer": "[email protected]"
}
The official Go implementation documents host-language boundaries: untyped numbers decode to float64; integers outside the interoperable range may become quoted strings; Go maps do not preserve source field order; tabs in indentation are rejected in strict mode. Test the types that matter to your application.
Round-trip tests should include:
- empty objects and arrays;
- strings that look like booleans, null, or numbers;
- delimiter, colon, quote, backslash, and newline characters;
- Unicode and normalization variants;
- large integers and decimals;
- mixed and deeply nested arrays;
- truncated rows and wrong declared lengths;
- implementation-to-implementation fixtures.
“Decode succeeded” is weaker than equality against the expected typed value.
A Reproducible Go Measurement
This example pins the official organization’s Go codec and one tokenizer implementation. It compares compact JSON with TOON for the same typed value and verifies the round trip.
go mod init toon-measure
go get github.com/toon-format/[email protected]
go get github.com/tiktoken-go/[email protected]
go run .
package main
import (
"encoding/json"
"fmt"
"reflect"
"github.com/tiktoken-go/tokenizer"
"github.com/toon-format/toon-go"
)
type User struct {
ID int `json:"id" toon:"id"`
Name string `json:"name" toon:"name"`
Role string `json:"role" toon:"role"`
}
type Payload struct {
Users []User `json:"users" toon:"users"`
}
func tokenCount(encoder tokenizer.Codec, text string) (int, error) {
ids, _, err := encoder.Encode(text)
if err != nil {
return 0, err
}
return len(ids), nil
}
func main() {
input := Payload{Users: []User{
{ID: 1, Name: "Ada", Role: "admin"},
{ID: 2, Name: "Bob", Role: "user"},
{ID: 3, Name: "Lin", Role: "reviewer"},
}}
jsonBytes, err := json.Marshal(input)
if err != nil {
panic(err)
}
toonText, err := toon.MarshalString(input)
if err != nil {
panic(err)
}
encoder, err := tokenizer.Get(tokenizer.Cl100kBase)
if err != nil {
panic(err)
}
jsonTokens, err := tokenCount(encoder, string(jsonBytes))
if err != nil {
panic(err)
}
toonTokens, err := tokenCount(encoder, toonText)
if err != nil {
panic(err)
}
var decoded Payload
if err := toon.UnmarshalString(toonText, &decoded); err != nil {
panic(err)
}
if !reflect.DeepEqual(input, decoded) {
panic("round trip changed the payload")
}
fmt.Printf(
"encoding=cl100k_base json=%d toon=%d delta=%d round_trip=true\n",
jsonTokens,
toonTokens,
toonTokens-jsonTokens,
)
}
With the pinned dependencies above, this fixture prints:
encoding=cl100k_base json=41 toon=33 delta=-8 round_trip=true
That is one measured fixture, not a general percentage. Repeat the test with production-shaped payloads and the tokenizer used by the actual model. Include any format explanation in the measured prompt.
Evaluate End-to-End
Use a matrix:
| Dimension | What to measure |
|---|---|
| Size | Input, output, explanation, and repair tokens |
| Parsing | First-pass validity, strict errors, truncation detection |
| Semantics | Exact fields, values, types, and missing data |
| Model behavior | Comprehension, generation, tool selection, final task success |
| Operations | Encode/decode CPU, latency, memory, retries |
| Compatibility | Model, tokenizer, language, library, schema |
| Security | Injection, oversized values, malformed nesting, authorization |
Compare at least compact JSON and TOON. Add CSV only for truly flat tables and constrained JSON when the selected endpoint supports it.
The decision metric should be cost per accepted task:
(all prompt + completion + repair + downstream cost)
/ valid and semantically correct outcomes
A format that saves 15% on the first request but doubles repairs can lose overall.
Security Boundaries
TOON is syntax, not a trust mechanism.
- Never interpolate untrusted values into hand-built TOON; use a conforming encoder.
- Decode in strict mode with depth, size, row, and time limits.
- Validate the decoded value against an application schema.
- Preserve source and trust metadata outside the encoded text.
- Treat decoded strings as data even if they contain instructions.
- Authorize tool calls and side effects after decoding.
- Do not place secrets in a prompt merely because the format is compact.
The specification's length declarations help detect some malformed inputs, but they do not prevent prompt injection, data poisoning, or unauthorized actions.
Migration and Rollback
Introduce TOON behind an experiment flag:
- freeze representative payloads and expected outputs;
- pin spec, codec, tokenizer, model, and prompt;
- compare compact JSON and TOON offline;
- shadow production inputs without changing user-visible results;
- canary only on a low-risk, read-only path;
- monitor parse errors, repairs, task quality, latency, and cost;
- fall back to JSON when the schema, model, or data shape is unsupported.
Do not store only the TOON rendering if the application needs durable interchange. Keep the typed source and its schema so the representation can be regenerated after a draft or library change.
Frequently Asked Questions
What is TOON?
TOON is a line-oriented, indentation-based encoding of the JSON data model intended for LLM input. It declares array lengths and can declare shared fields once for uniform records. The current v4.1 document is a Working Draft, so deployments should pin the specification and codec.
How many tokens does TOON save?
There is no portable percentage. Count compact JSON and TOON with the exact tokenizer over representative payloads, then include format instructions, outputs, parse failures, repairs, and retries in the end-to-end comparison.
Is TOON lossless?
The specification defines deterministic round trips for its JSON data model, but host-language normalization and implementation limits still matter. Test numeric precision, ordering, Unicode, timestamps, edge strings, truncation, and cross-implementation fixtures.
Should an LLM generate TOON output?
Only after a direct comparison. TOON generation may incur instruction and repair costs, while a provider's constrained JSON feature may produce a stronger machine-consumable contract. Measure first-pass semantic correctness, not syntax alone.
Does TOON improve security?
No. It can expose lengths and structure to a strict decoder, but it cannot establish provenance, prevent prompt injection, authorize a tool, or validate a business action. Continue to treat every decoded value as untrusted input.
Common Failure Modes
- promising a fixed 30%, 40%, or 50% saving;
- comparing TOON with pretty JSON but deploying compact JSON;
- estimating tokens from character count;
- ignoring instructions and repair turns;
- using TOON for irregular or deeply nested data without measurement;
- asking a model to emit TOON when constrained JSON is available, without comparison;
- assuming any model understands the format without examples or testing;
- decoding non-strictly and accepting partial output;
- treating a successful round trip as proof of model accuracy;
- replacing public JSON APIs or storage solely for prompt compression;
- omitting codec, spec, tokenizer, and model versions;
- treating compact syntax as protection from injection.
Decision Checklist
- [ ] Confirm that repeated keys dominate a meaningful payload.
- [ ] Compare against compact JSON with the same data.
- [ ] Count with the exact target tokenizer.
- [ ] Include format instructions, outputs, repairs, and retries.
- [ ] Pin TOON v4.1 or the exact supported revision and codec.
- [ ] Test strict round trips across edge-case fixtures.
- [ ] Measure model comprehension and generation separately.
- [ ] Use semantic and business validation after decoding.
- [ ] Keep identity, authorization, and side effects outside the format.
- [ ] Roll out behind a flag with JSON fallback.
Related Resources
- Tokens and Context Windows
- Constrained Decoding and Structured Output
- JSON Data Format
- Token
- JSON to TOON Converter
- TOON to JSON Converter
Primary Sources
- TOON v4.1 Specification
- TOON for Go v0.1.0
- TOON vs JSON: Plain and Constrained Decoding Generation
- Notation Matters: Token-Optimized Formats in Agentic Systems
- RFC 8259: The JSON Data Interchange Format
Conclusion
TOON is useful when its data shape, tokenizer, model, and workflow align. Its tabular forms can remove repeated structure, but instruction overhead, parse failures, retries, and semantic errors determine whether that compression survives end to end. Keep JSON as the durable application contract, pin the TOON revision, measure complete requests, and adopt the format only where cost per accepted task improves without weakening reliability.