What Is TOON? Token-Oriented Object Notation Explained

TOON (Token-Oriented Object Notation) is a compact, human-readable data format that represents the same data as JSON using about 43% fewer tokens, so more data fits into an LLM prompt for less money. It writes objects with YAML-style indentation and arrays of objects as CSV-style tables with a single header, and it converts losslessly to and from JSON.

// JSON
{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]}

// TOON
users[2]{id,name}:
  1,Alice
  2,Bob

That 43% figure is the average from the official TOON v4.1 benchmark (42.6% fewer tokens than JSON, with accuracy effectively tied at 72.2% vs 71.4%). You can try it on your own data with the JSON to TOON converter or compare token counts in the TOON token calculator.

TOON is a new data serialization format designed for the AI era. It is built on a simple premise: Data should be concise. Learn more at the official TOON website.

In the last 20 years, we optimized data for two things:
1. Network Bandwidth (Binary formats like Protobuf).
2. Browser Compatibility (JSON).

But today, the bottleneck has shifted. We are no longer constrained by bandwidth (5G is fast) or browsers (V8 is fast). We are constrained by Context Windows.

The "Context Crisis"

Every time you send a request to an LLM (GPT-5.6, Claude Sonnet 5.5, Gemini 3.8 Flash), you are renting "attention." This attention is measured in Tokens.

A token is roughly 0.75 words, and punctuation counts too.

• {"id": 1} spends tokens on braces and quotes as well as the key and value.
• id: 1 carries the same information with roughly half as many tokens.

The difference seems small until you realize that modern RAG (Retrieval Augmented Generation) applications inject megabytes of data into the prompt.

Anatomy of TOON

TOON looks like a blend of YAML and CSV. It is designed to be readable by both humans and LLMs.

1. The Object Block

Key-Value pairs are separated by newlines. No braces. Key and value are separated by a colon.

model: gpt-5.4-nano
temperature: 0.7
max_tokens: 100

Unquoted Strings: If a string doesn't contain special characters, it doesn't need quotes. This saves 2 tokens per string.

2. The List Block

Arrays of primitives go on one line. The header declares the length, and values are comma-separated. (Dash-prefixed list items are used only for mixed or non-uniform arrays.)

stops[3]: user,assistant,system

Empty arrays are always written as key: [].

3. The Table Block (The "Killer Feature")

This is where TOON shines. Arrays of objects are represented as tables.

messages[3]{role,content}:
  system,You are a helper.
  user,What is the capital of France?
  assistant,Paris.

The Header: messages[3]{role,content} tells the LLM:

• The data is in messages.
• There are 3 items.
• The fields are role and content.

The Body: Comma-separated values with no space after the delimiter. No repeated keys. Values that contain the delimiter are quoted.

4. What changed in TOON v4?

The current spec is TOON 4.1 (July 2026), implemented by @toon-format/toon 4.1.1. Version 4 added three things worth knowing:

• Keyed tables: an object whose values are uniform objects becomes a table with a [N:] header, and each row starts with its key.
• Nested field groups: uniform nested objects inside table rows stay tabular, e.g. customer{name,country} in the header.
• Full-line comments: a line starting with # is a comment. There are no inline or trailing comments, and encoders never emit comments.

flags[2:]{enabled,rollout}:
  darkMode: true,50
  newCheckout: false,0
orders[2]{id,customer{name,country},total}:
  1,Ada,UK,49.99
  2,Bob,US,199

Version 4 also removed key folding (dotted paths like a.b.c: 1), so nested objects are always written with indentation.

Why LLMs Love TOON

You might think: "Can the LLM understand this new format?"

Yes. In the current official benchmark (TOON 4.1, 5,856 calls across Claude Haiku 4.5, Gemini 3.6 Flash, GPT-5.4 nano and Grok 4.5), TOON scored 72.2% accuracy vs 71.4% for JSON while using 42.6% fewer tokens. The intervals overlap, so treat that as accuracy parity at a much lower token cost. LLMs handle the format well because they were trained on massive amounts of code, CSVs, and logs. They intuitively understand tabular structures.

By removing the syntactic noise (brackets, quotes), you allow the LLM's "Attention Mechanism" to focus on the Signal (the actual data values) rather than the Noise (the structure).

How to Adopt TOON

You don't need to rewrite your database.

Step 1: Install the library

npm install @toon-format/toon

Step 2: Convert at the Edge

In your API route (Next.js/Express), convert your JSON data to TOON before constructing the prompt.

import { encode } from "@toon-format/toon";

const users = await db.users.findMany();
const prompt = `
  Analyze these users:
  ${encode({ users })}
`;

Step 3: Enjoy the Savings

For uniform, table-like data you will see an immediate drop in token usage (measure yours in the token calculator). The official benchmark measures 42.6% fewer tokens than formatted JSON overall, about 59% on flat tables and about 33% on mixed structures. Deeply nested or irregular data saves less, and compact JSON can win there.

FAQ