What the TOON Format Is (Token-Oriented Object Notation)

How TOON Can Change the Way AI “Sees” Data

In the world of modern artificial intelligence—particularly when working with Large Language Models (LLMs)—every token matters. API cost, as well as latency and prompt efficiency, depend directly on how many tokens are sent to the model. In this context, TOON (Token-Oriented Object Notation) emerges as a compact, readable serialization format designed specifically to minimize the number of tokens required to represent structured data.

Instead of using the classic JSON format (or others), TOON “packages” the same information in a leaner, more optimized way while remaining easily readable by humans.

Let’s take a closer look at what TOON is, why it’s useful, how it works, its limitations, and its current status.

Why TOON Matters Now

The Problem with JSON in AI Pipelines

JSON is widely used to represent structured data. However, it has a “verbose” grammar: curly braces { }, brackets [ ], quotes ", commas, indentation… all of this generates extra tokens when sending payloads to an LLM.

When dealing with many uniform objects (for example, a list of users, products, or records), keys are repeated continuously, further increasing token consumption.

The Solution? TOON!

TOON was created precisely to solve this problem: it is a format designed to maximize token efficiency while maintaining human readability and the full semantic structure of JSON. According to several benchmarks, TOON can reduce token usage by 30–60% compared to traditional JSON. This reduction translates into lower API costs, more available space within the model’s context window, and—in some cases—greater accuracy in the model’s understanding of structured data.

At Openapi we are working in the same direction, and soon (in the coming weeks) our APIs will also support the new format.

What TOON Is: Definition and Principles

TOON stands for Token-Oriented Object Notation. It is a text-based serialization format for structured data, designed specifically to be sent to LLMs as input. TOON is:

According to the official GitHub repository, TOON is lossless with respect to JSON: you can convert JSON → TOON → JSON without any loss of information.

How the TOON Format Works

Basic Syntax

1. Simple Objects

TOON removes curly braces and uses indentation for nesting. 

For example:

id: 123 name: Ada active: true 

This represents the same JSON object

{ "id": 123, "name": "Ada", "active": true }

2. Nested Objects

Using YAML-like indentation:

user: id: 123 name: Ada

JSON representation

{ "user": { "id": 123, "name": "Ada" } } 

3. Arrays of Primitives

TOON declares the length and values inline:

tags[3]: foo,bar,baz 

This is equivalent to

["foo", "bar", "baz"] 

in JSON.

4. Uniform Object Arrays (Tabular Arrays)

This is where the major token savings occur:

users[2]{id,name,role}: 1,Alice,admin 2,Bob,user 

The lines below contain comma-separated values, one per object.

5. Delimiter Options

To separate row values, TOON supports multiple delimiters: comma (,), tab (\t), or pipe (|). Using tabs or pipes can offer additional token savings because it reduces the need for quoting or escaping.

6. Key Folding

The TOON specification includes a “key folding” option: if a structure contains chains of single-level “wrapper” keys, they may be represented using dotted paths to save tokens.

7. String Quoting

Strings in TOON are quoted only when necessary: for example, if they contain the active delimiter, colons :, leading/trailing spaces, control characters, etc.

8. Special Type Conversion

How TOON Works (For Non-Developers)

For those who are not developers, think of TOON as a leaner “language” for describing data.

When sending a group of similar elements (e.g., a list of users, all with name, age, and role), TOON allows you to declare the fields once (name, age, role) and then provide each row of data. This way, you don’t have to rewrite “name”, “age”, “role” for every user as you would in standard JSON—saving valuable “fuel” (tokens). If the data is simple (like just a list of tags or words), TOON represents everything compactly: fewer symbols, less “unnecessary punctuation”. For nested data (e.g., an object inside another), TOON uses indentation (spaces) to show hierarchy, similar to a well-structured document but without heavy brackets.

In short: TOON preserves the logical structure of data while reducing “empty words.”

What Are the Advantages of TOON?

Below are the advantages of using the TOON format:

1. Token Efficiency

Thanks to its minimal syntax, single declaration of keys, and tabular structure, TOON enables an average 30–60% token reduction compared with JSON. This savings is especially significant in LLM workloads involving repetitive tabular data.

2. Higher Accuracy (Schema-Aware Guardrails)

TOON is not merely compact: it is schema-aware. Declaring array length ([N]) and fields ({…}) helps LLMs validate structure more effectively, reducing errors, omissions, and hallucinations when the model must answer questions or reason about structured data. In the official repository, benchmarks show that TOON can achieve higher retrieval accuracy compared to compact JSON.

3. Human Readability

Despite reducing symbols, TOON remains readable for developers thanks to indentation, tabular organization, and very clear syntax. This facilitates debugging, manual prompt writing, and interpretation by prompt engineers.

4. Compatibility and Zero Information Loss

TOON is lossless relative to JSON: any JSON structure can be expressed in TOON and converted back without data loss. Libraries and SDKs exist for encoding (encode) and decoding (decode) between JSON and TOON in various languages (e.g., TypeScript, Elixir, PHP).

5. Cross-Language Implementations

TOON is not just a conceptual idea: there are concrete implementations in many languages:

More languages continue to emerge thanks to the open-source nature of the specification.

When TOON Is Particularly Useful

TOON provides maximum benefit in certain common scenarios:

When Not to Use TOON

It is important to note that TOON is not always the ideal choice. There are cases where other formats may be more efficient:

How to Use TOON in LLM Prompts

Encoding Before Sending

You can use official libraries to convert JSON objects into TOON: for example, with the official TypeScript package (@toon-format/toon)

When building the prompt, include the serialized TOON in a code block, for example:

```toon users[3]{id,name,role}: 1,Alice,admin 2,Bob,user 3,Charlie,user 

This helps the model identify the structure and respond consistently.

Generating TOON from the LLM

If we want the model to generate TOON data, we can:

This pattern is helpful because the model doesn’t need to “guess” key names every time—they are already declared.

Simple Tools for Using TOON

You don’t need to be a programming expert to experiment with TOON. There are tools designed for people who have data but don’t want to write complex code:

Current Status of the TOON Project and Roadmap

The TOON project is active and open-source. The official GitHub repository includes the specification, code, and benchmarks. The official specification (spec) is updated to version 2.0 (working draft). Implementations already exist in many languages, as noted above (TypeScript, Elixir, PHP, R, etc.), and more may arrive. There are tools and web converters (e.g., ToonParse) to convert JSON → TOON and vice versa on the client side, without sending data to external servers. Benchmarks indicate that TOON not only reduces tokens but may also improve retrieval accuracy when using LLMs with structured data.

Caveats and Caution: What Is Not Yet Confirmed

As highlighted by community comments, many LLMs have not been explicitly “trained” on TOON: their training data likely consisted almost entirely of JSON or other formats. This means that using TOON may require adaptation, and in some cases, the model may respond less optimally if it is not “familiar” with the structure. Although open-source and rapidly evolving, TOON is still relatively new. The specification is in flux, so some implementations may not be fully compatible with each other unless the correct spec version is followed.

In Summary

TOON (Token-Oriented Object Notation) represents a significant innovation in data serialization for LLM applications. Thanks to its compact, human-readable, and schema-aware structure, it can drastically reduce the number of tokens compared to traditional JSON (often by as much as 60%) while preserving full semantic meaning and data structure.

However, it’s important to stay realistic: not all scenarios are suited to TOON yet. At present, TOON is a complement to JSON—useful when token savings provide economic or technical value, but not yet a universal replacement.

If you are a developer working with LLMs, TOON is worth exploring: you can use it to build more efficient prompts, optimize API costs, and increase the usable space within the model’s context window. But keep a pragmatic approach: always measure the benefits for your specific use case and test JSON ↔ TOON conversion reliability in your pipeline.

Openapi is about to support TOON in its APIs, and this is a very important update: it means applications relying on these APIs can become more efficient and less expensive by leveraging a modern, optimized format.