EN
Ihor NikolenkoEvery prompt you send to a language model gets billed in tokens. And a good chunk of those tokens go not toward meaning, but toward wrapping: quotes, colons, curly braces, and field names repeated in every single record. Send the model one record, and you won't notice. But when an automation loads hundreds of rows from a CRM or spreadsheet into a prompt every hour, that wrapping starts costing more than the data itself.
This matters right now because AI automation has stopped being an experiment. In n8n, in agent systems, in RAG pipelines, data gets shuttled between steps dozens of times a day, and every step is a separate token bill. Then there's the context window: the more room the wrapping eats up, the less is left for actual meaning, and the model starts "forgetting" the start of the conversation.
In this article, I'll break down TOON — Token-Oriented Object Notation, a format built specifically so an LLM can read the same data more compactly. What it is, how it looks next to JSON, where the savings are real and where they aren't, and how to plug TOON into your automation without rewriting the whole system.
What TOON Is, and Why It's Not "Just Another YAML"
Most people's first reaction is: "Great, another format — we already have JSON, YAML, TOML, CSV, Protocol Buffers." The difference is who it's for. JSON was built for programs talking to each other; YAML was built for configs a human reads. TOON was built for a reader that thinks in tokens. It's not about readability or strict schemas — it's about letting a model see the structure of the data while spending the fewest possible tokens on it, without getting confused.
The idea is almost embarrassingly simple. If you have an array of identical objects — say, a thousand orders with the same fields — JSON repeats those field names a thousand times. TOON writes the field names once, in a header, and then lists only the values, row by row, separated by a delimiter. It's basically what a table looks like when you describe it as plain text.
Two more things set TOON apart from plain CSV. First, the array header carries the row count in square brackets, so the model knows exactly how many records to expect — a built-in sanity check: if the row count is off, something got lost. Second, TOON can describe nested structures through indentation, the way YAML does, so it isn't limited to flat tables.
What TOON Looks Like Next to JSON
Take three users with an id, a name, and a city. In JSON, that's an array of three objects, each repeating the field names, with quotes around every string value, plus brackets and commas. In TOON, the same data looks like this (value rows are indented under the header):
users[3]{id,name,city}:
1,Olena,Kyiv
2,Max,Lviv
3,Anya,Odesa
Read the header like this: array users, containing 3 records, each with the fields id, name, city. Then come the values themselves. Quotes aren't needed unless a value contains the delimiter or a special character — in that case, it gets quoted, just like in CSV.
A plain object with no array is written as "key: value" pairs, each on its own line. An array of primitives is a single line: the name, the count in brackets, a colon, and the values separated by commas. Nested objects sit indented under their parent key. In other words, every structure you're used to seeing in JSON is still here — just without the characters the model would otherwise have to "read and ignore."
Here's an important detail: the delimiter between values in the table section doesn't have to be a comma. The spec allows a tab or a pipe character, which is a lifesaver when your data is full of text with commas everywhere — product descriptions, addresses, comments. Switch the delimiter, and you no longer need to quote half your values.
Where the Savings Are Real, and Where They Aren't
I want to be honest here, because big-percentage promises have already started circulating around TOON. The format's author publishes benchmarks in the repository, and they show a substantial reduction in token count compared to JSON on tabular data. But your actual results depend on the shape of your data, and here's how that plays out in practice.
- Homogeneous arrays of objects — the main use case. Lists of orders, leads, products, report rows, search results. The more records and the more fields each one has, the bigger the savings, because that's exactly where JSON repeats itself the most.
- A single object with a dozen fields — there are savings, but small ones. There's little wrapping and no repetition, so the difference comes to a few dozen tokens. Not worth rewriting a prompt for.
- Deeply nested, heterogeneous structures — where every record has its own set of fields, or nested arrays of different lengths. TOON still works here, but its edge over JSON shrinks, and sometimes disappears entirely. The format's own documentation says as much.
- Short prompts — if your data is only a couple of lines, the format doesn't matter. The cost is driven by the instructions, not the data.
The simplest way to stop guessing is to measure. Take a real chunk of data that's currently going into your prompt, count the tokens in both JSON and TOON using your provider's tokenizer, and compare. For me, the difference was noticeable on lead lists and search results, but not on single-record cards. That's ten minutes that will save you from rewriting something that wouldn't have paid off anyway.
TOON, JSON, YAML, and CSV: What Each One Is For
| Criterion | JSON | YAML | CSV | TOON |
|---|---|---|---|---|
| Built for | Programs | Humans (configs) | Tables | Language models |
| Field name repetition | Every record | Every record | Once | Once |
| Nested structures | Yes | Yes | No | Yes, via indentation |
| Built-in count check | No | No | No | Yes, a counter in the header |
| Ecosystem and API support | Everywhere | Wide | Wide | Young, libraries exist |
| Use as your canonical format | Yes | Yes | For flat data | No — prompts only |
The key takeaway from that table is the last row. TOON doesn't replace JSON in your database, your API, or your config files. It lives in exactly one place: the boundary between your system and the model. Your data keeps being stored the way it always was, gets converted to TOON right before it hits the prompt, and gets converted back afterward if needed.
How to Plug TOON into Your Automation
The format's spec and official implementation live in the open-source toon-format/toon repository on GitHub — it includes a JavaScript/TypeScript library, a command-line conversion utility, and links to community implementations in other languages. Below is the setup I use in n8n, but it works the same way for any orchestrator or custom code.
- Leave your data source alone. Your CRM, spreadsheet, or database keeps outputting JSON. You don't change anything in your integrations.
- Convert right before the prompt. A dedicated step (in n8n, a Code node with the library attached, or a call to the CLI utility) takes the array of records and returns a TOON string.
- Give the model one hint. Don't assume the model "knows" TOON. A single line in the system prompt along the lines of "the data below is in TOON format: the header lists the array name, row count, and field names, followed by comma-separated values" clears up most misunderstandings.
- If you need a structured response, ask for TOON there too. Describe the expected header (array name and fields), and the model will return data in the same compact form. Then convert it back to JSON and process it as usual.
- Check the counter. The number in square brackets is your free integrity test. Fewer rows than declared means the model dropped something, and that case needs to be handled, not passed further down the chain.
A separate note on agent systems. When Agent A passes results to Agent B, who passes them on to Agent C, every handoff is a prompt full of data. TOON pays for itself fastest here, because the same data passes through a model multiple times. But the rule stays the same: data travels between agents as TOON, while storage and logging stay in JSON so you can still read and parse it whenever you need to.
The Most Common Mistakes I See
- Using TOON as a storage format. Someone starts writing logs or API responses in TOON. Don't: there are orders of magnitude more tools for parsing JSON, and nobody cares about saving tokens in storage.
- Commas in the data without switching the delimiter. Product descriptions with commas turn the table into a mess. Either quote those values or switch the delimiter to a tab.
- Heterogeneous records in one table. If half your records are missing a field, the tabular form breaks. Either normalize the data ahead of time by filling in empty values, or pass those records as nested objects instead.
- Adopting it without measuring first. The most common one. You rewrite every prompt, and the bill doesn't budge because the data was small to begin with. Measure first, change second.
- No legend for the model. The model gets an unfamiliar format with no explanation and starts "guessing" the structure. One line of explanation makes the problem disappear.
If you're building an AI automation right now and aren't sure exactly where your tokens and time are leaking, this is exactly the situation where one hour of conversation saves you weeks. In a 60-minute consultation, I look at your pipeline's architecture and hand you a 30-day plan: what to convert, what to leave alone, and what to measure first.
The Short Version
- TOON is a data format built for prompts: field names are written once, only the values follow, and the row count sits right in the header.
- The biggest savings show up on homogeneous arrays of records: lists of leads, orders, products, and search results.
- On single objects and deeply nested heterogeneous structures, the advantage is small or nonexistent — the spec itself admits as much.
- TOON lives only at the "system → model" boundary; your database, API, and logs stay on JSON.
- The model needs a short legend for the format in the system prompt, or it will guess at the structure.
- The row counter in the header is a free check that the model didn't lose anything.
- Before adopting it, count the tokens on your own real data — that's ten minutes that decide whether changing anything is worth it at all.
Frequently Asked Questions
Do language models understand TOON without extra training?
Yes, as long as you give a brief explanation of the structure in the prompt. The format is deliberately built from familiar elements — a header, a list of fields, delimiter-separated rows, indentation for nesting — so the model reads it as a labeled table. Without a legend, results get less predictable, which is why I consider that one line of explanation mandatory.
Can I replace JSON with TOON across my whole system?
You shouldn't. TOON solves one problem: reducing the number of tokens in a prompt. For storage, service-to-service communication, and logging, JSON remains the better choice thanks to its tooling ecosystem. The right setup is: store in JSON, convert to TOON right before the prompt, and convert back afterward if needed.
What if my data has commas, quotes, or line breaks?
Either quote those values, the way CSV does, or switch the delimiter to a tab or a pipe character — the spec allows both. For text fields with long descriptions, switching the delimiter is usually more convenient.
How do I find out how much I'll actually save?
Take a real chunk of data from your prompt, convert it to TOON, and count the tokens both ways using your provider's tokenizer. The difference depends on the number of records and fields, so other people's benchmarks are just a reference point, not a promise for your own data.
Does TOON work for model responses, not just input data?
It does. If you describe the expected header — the array name and the field list — the model will return a tabular response in TOON, saving you tokens on the output side as well. From there, a library parses it and turns it back into a regular object for the next steps.
