JSON, TOON, TONL, CSV & More Data Format Documentation

Which format is for what

Every format on this site converts to and from JSON, but each one was designed for a different reader. Pick the format by who or what consumes the data, not by habit.

• JSON is the interchange default: every language parses it and every API speaks it. It is also the most repetitive format, because each object repeats its keys, quotes, and braces.
• TOON encodes the same data model as JSON for LLM input. Arrays of objects with the same fields become one header line plus one comma-separated row per record, and nesting is expressed by indentation instead of braces.
• TONL is also a compact JSON encoding, but it is built around tooling: a query API, schema validation with TSL, and streaming for large files.
• CSV is for spreadsheets and bulk imports. It only holds flat rows, and every value is text.
• YAML and TOML are configuration formats meant to be edited by people. YAML dominates DevOps tooling; TOML is the standard for pyproject.toml and Cargo.toml and always has a table at the top level.
• XML remains common in SOAP services, feeds, and document formats. It has attributes, which JSON does not, so converters map them to prefixed keys.
• Protobuf is a schema-first binary format for service-to-service traffic. This site works with its text format; binary encoding still needs a .proto schema.

When TOON saves tokens, and when it does not

TOON uses about 43% fewer tokens than JSON on average (42.6% in the official TOON v4.1 benchmark; see our breakdown), ranging from about 33% on mixed/nested structures to about 59% on flat uniform tables. The spread comes from data shape. The biggest savings appear when a payload is mostly a list of records that share the same fields, such as database rows, search results, log lines, or product catalogs, because the field names are written once instead of once per record.

Deeply nested or irregular data saves much less. Objects whose keys differ from record to record cannot use the tabular form, so TOON falls back to indented key: value lines, which are only modestly shorter than minified JSON. Configuration files, single large objects, and payloads dominated by long free-text strings fall into this group. The when not to use TOON and nested data handling articles go through these cases. Before switching a pipeline, convert a real payload and compare the output sizes yourself.

TOON is a prompt-side format. Keep JSON for storage, APIs, and anything a program parses. Convert to TOON just before the data goes into the model, and convert TOON answers back with TOON to JSON.

TOON or TONL?

Both formats encode the full JSON data model and round-trip without loss. TOON is the smaller, simpler choice when the only goal is fewer tokens in a prompt. TONL adds a #version header, a root wrapper, and field lists on each object, so on small payloads it is usually larger than TOON. Choose TONL when you need its query, aggregation, schema, or streaming features; the TONL project reports savings of roughly 32-45% versus JSON in its own measurements. The TOON vs TONL comparison covers the trade-offs in detail.

Where to go next

• Read the TOON specification first, then the syntax cheat sheet for quick reference.
• Try a conversion: JSON to TOON, CSV to TOON, or browse every pair in the conversion hub. Each pair page shows a real sample conversion and the caveats for that pair.
• Use TOON in code with the TypeScript or Python libraries, or see all language implementations.
• Automate conversions with the conversion API.