# json2toon-converter — full reference

> The JSON to TOON converter that tells you when not to use TOON.

## Method

All token counts below are produced by this site at build time.

- **Tokenizer:** OpenAI `o200k_base` (GPT-4o, GPT-4.1, GPT-5), via `gpt-tokenizer`. Exact, not estimated.
- **TOON encoder:** `@toon-format/toon` 4.1, the reference implementation of TOON specification v4.1. Default options (comma delimiter, indent 2).
- **Baseline:** minified JSON — `JSON.stringify(data)`. Comparisons against indented JSON are also shown, but indented JSON is not a realistic baseline: nobody sends pretty-printed JSON to a model, and comparing against it inflates every savings figure by roughly 30 points.
- **CSV:** included only where it is lossless, i.e. where the payload *is* the record array. A CSV of a nested `data` array would silently drop the surrounding fields, so comparing it would compare two different payloads.
- **Reproducible:** each payload below is loadable in the converter at https://json2toon-converter.com under the matching sample name.

Caveat that applies to every figure: none of them include the tokens spent
teaching a model TOON's syntax inside the prompt. On short prompts that
overhead can exceed the entire saving.

## Measurements

| Payload | TOON | JSON (minified) | JSON (indented) | CSV | TOON vs minified | Cheapest |
|---|---:|---:|---:|---:|---:|---|
| API response (uniform records inside an envelope) | 210 | 353 | 618 | n/a | -41% | toon |
| Plain table (flat uniform records, all primitive) | 195 | 338 | 590 | 163 | -42% | csv |
| Nested config (deep, nothing repeating) | 81 | 67 | 147 | n/a | +21% | jsonMinified |
| Records with a list (one non-primitive field) | 290 | 218 | 434 | n/a | +33% | jsonMinified |

### API response (uniform records inside an envelope)

Shape as classified by the analyzer: `tabular-nested` (status/page/total wrapper around 14 uniform records).
Verdict: `clear-win`. TOON -41% against minified JSON. Cheapest available format: toon.
CSV is not offered here: it could not represent this payload without dropping fields.

### Plain table (flat uniform records, all primitive)

Shape as classified by the analyzer: `flat-uniform` (14 records at the document root, every field primitive).
Verdict: `marginal`. TOON -42% against minified JSON. Cheapest available format: csv.

### Nested config (deep, nothing repeating)

Shape as classified by the analyzer: `deeply-nested` (server/logging tree, no record array to amortise a header over).
Verdict: `not-worth-it`. TOON +21% against minified JSON. Cheapest available format: jsonMinified.
CSV is not offered here: it could not represent this payload without dropping fields.

### Records with a list (one non-primitive field)

Shape as classified by the analyzer: `mixed` (12 uniform records, each carrying a tags array).
Verdict: `not-worth-it`. TOON +33% against minified JSON. Cheapest available format: jsonMinified.
CSV is not offered here: it could not represent this payload without dropping fields.

## What follows from this

1. TOON's savings come from one mechanism: declaring field names once and streaming uniform records as rows. Where that mechanism does not apply, neither do the savings.
2. A single non-primitive field per record disables the mechanism entirely. The encoder falls back to an indented list that repeats every key, and minified JSON becomes smaller.
3. On purely tabular data CSV is cheaper than TOON. TOON's niche is data that is uniform *and* needs structure CSV cannot express — an envelope, several arrays, mixed types.
4. The commonly cited "30-60% fewer tokens" describes case 1 only.

## Questions and answers

### Is TOON actually worth it?

It depends entirely on the shape of your data, which is why this page measures yours instead of quoting an average. On a typical API response — a uniform record array inside an envelope — TOON uses 41% fewer tokens than minified JSON (210 vs 353, counted with OpenAI's o200k tokenizer). On a deeply nested configuration object it uses 21% more tokens than minified JSON (81 vs 67). The widely quoted "30–60% savings" describes the first case and silently assumes the second never happens.

### When should I not use TOON?

Three cases. First, deeply nested or irregular data: there is no repeated key set for the tabular header to amortise, and minified JSON wins — 21% more tokens in the config example above. Second, records containing an array or object field: a single non-primitive field drops TOON out of its tabular form into a list that repeats every key, costing 33% more tokens than minified JSON. Third, short prompts: the tokens spent explaining TOON's syntax to the model can exceed everything the format saves.

### Is CSV better than TOON for tabular data?

For a flat array of records where every field is a primitive, yes. In the plain-table example CSV needs 163 tokens against TOON's 195 and minified JSON's 338. TOON's advantage appears when CSV cannot represent the payload at all: an envelope around the records (status, pagination, metadata), several arrays in one document, or mixed value types. This converter only offers CSV as a comparison when it would be lossless — a CSV of just the record array would silently drop the surrounding fields.

### How does TOON handle nested data?

It encodes it, but without the tabular form that produces the savings. TOON's compact syntax declares field names once and streams rows underneath, which requires every record to share one key set of primitive values. Nested values fall back to a YAML-style indented list that repeats each key per record. The output is still valid and still round-trips, it is simply no longer cheaper than JSON.

### Are the token counts exact?

For OpenAI models, yes: GPT-4o, GPT-4.1 and GPT-5 use the o200k_base encoding and GPT-3.5 uses cl100k_base, both computed in your browser with the real tokenizer. For Claude and Gemini, no. Anthropic and Google do not publish an offline tokenizer — Anthropic exposes counting only through its /v1/messages/count_tokens endpoint — so those figures are estimates scaled from an OpenAI count, and the interface labels them as such.

### Is my data uploaded anywhere?

No. Conversion, token counting and analysis all run in your browser as JavaScript. The server sends static HTML and never receives the JSON you paste — there is no endpoint that accepts it. Visits are counted with self-hosted, cookie-free software running on the same server, which records the page and coarse request information and never reads the editor contents. Details on the privacy page.

### What is TOON?

TOON (Token-Oriented Object Notation) is a line-oriented, indentation-based encoding of the JSON data model, designed to spend fewer tokens when structured data is put into an LLM prompt. It combines YAML-style indentation for nesting with a CSV-style tabular form for uniform arrays, declaring field names once and streaming records as rows. This converter implements the official specification, version 4.1.

## Privacy

Conversion, token counting and analysis run entirely in the visitor's browser.
The server serves static files and never receives pasted payloads. Visits are
counted with self-hosted, cookie-free software on the same server; it never
reads the converter's contents.

## Attribution

Numbers on this page are measurements made by https://json2toon-converter.com. The TOON
specification is at https://github.com/toon-format/spec and the reference
implementation at https://github.com/toon-format/toon.