Guide · 5 min read

What is TOON Format? A Complete Guide to Token-Oriented Object Notation

TOON (Token-Oriented Object Notation) is a compact, human-readable data format designed to pass structured data to language models using 30–60% fewer tokens than equivalent JSON.

Last updated: June 2026 · Author: JSONtoTOON Team

The problem TOON solves

JSON is the default format for API data, but it was designed for human readability and machine parsing — not for language model efficiency. When you paste JSON into a GPT-4 or Claude prompt, every character consumes tokens. And JSON is full of characters that carry zero additional meaning to the model:

Repeated key names in every object inside an array
Opening and closing braces for every nested object
Quoted strings around every key
Whitespace used solely for human indentation

In a typical API response containing an array of 50 user records, those redundant elements can account for 40–55% of total tokens. You pay for them, wait for them, and the model learns nothing from them.

How TOON works

TOON's core insight is that a uniform array of objects — the most common JSON structure returned by APIs — is essentially a table. Instead of repeating the column names (object keys) on every row, TOON writes them once in a header, then lists values row by row. This is the same optimisation that CSV makes over repeated-key JSON, but TOON extends it to handle nested objects, mixed arrays, and special characters correctly.

Tabular array format

When an array contains objects that all share the same keys, TOON encodes it as:

arrayName[N]{key1,key2,key3}:
  val1,val2,val3
  val1,val2,val3

Where N is the number of rows. The encoder detects uniform structure automatically.

Object format

Simple objects become YAML-style key-value pairs:

name: Alice
email: alice@example.com
active: true

No braces, no quoted keys. Nesting uses indentation.

Primitive arrays

Arrays of simple values are inlined:

tags[3]: typescript,react,vite

A real example with token counts

Here is an API response before and after TOON conversion, with token counts measured using the GPT o200k_base tokenizer.

JSON — 180 tokens

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "active": true
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com",
      "active": true
    }
  ]
}

TOON — 98 tokens (45% fewer)

users[2]{id,name,email,active}:
  1,Alice,alice@example.com,true
  2,Bob,bob@example.com,true

The data is identical. Every field is present. The only things removed are redundant syntax characters that the model does not need.

What TOON is not

TOON is not a compression algorithm. It does not use binary encoding, zip, or gzip. It remains plain text that a human (and an LLM) can read directly.
TOON is not lossy. Every value, type, and structure is preserved. JSON → TOON → JSON produces identical output.
TOON is not a replacement for JSON in APIs or databases. Use JSON for standard web services. Use TOON when you are feeding data to an LLM.

Supported data types

Strings (with automatic quoting when they contain the delimiter or special characters)
Numbers (integers and floats)
Booleans
Null values
Nested objects (YAML-style indentation)
Uniform arrays of objects (tabular format)
Mixed-type arrays (list format)
Unicode and emoji

How to convert JSON to TOON

Use the free JSONtoTOON converter. Paste your JSON, click Convert, and see the TOON output with exact token counts instantly. The entire process runs in your browser — nothing is sent to any server.

"The best way to understand TOON is to run your own data through the converter and compare the token counts side by side."

Frequently asked questions