What is TOON and Why Use It?

If you are working with LLMs like GPT-4, Claude 3.5, and Gemini, you know that "tokens" are money. The more tokens you send, the more you pay, and the slower your model responds.

TOON is a modern data serialization format designed specifically to fix the "bloat" of JSON.

Standard JSON is great for APIs, but it's heavy on syntax. It repeats keys for every single item in a list and uses tons of braces {}}, quotes "", and commas. TOON strips all that noise away. It combines the clean look of YAML (indentation) with the density of CSV (tables) to make your data up to 50% smaller in token count.

See the Difference (JSON vs. TOON)

The best way to understand TOON is to see it. Look at how much cleaner and more compact the TOON version is for a simple list of users.

{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "editor" },
    { "id": 3, "name": "Charlie", "role": "viewer" }
  ]
}

users[3]{id,name,role}:
  1, Alice, admin
  2, Bob, editor
  3, Charlie, viewer

Why This Tool is a Game-Changer for LLM Devs

There are three main reasons developers are switching their LLM context to TOON:

• Since LLMs bill by the token, cutting your data size by 30-50% directly cuts your monthly invoice. If you're regularly sending long lists of products, logs, or user history to ChatGPT, the savings add up fast.
• Fewer tokens means the model processes your prompt faster. That reduced latency is noticeable in production apps where response time matters.
• LLMs have a "memory limit" — the context window. By compressing your data with TOON, you fit more information into that window without confusing the model. You're not losing data; you're just packing it more efficiently.

When to Use TOON (and When Not To)

• ✅ USE IT FOR: Large lists of similar items. If you have an array of 50 products, 100 log entries, or a long transaction history, TOON is perfect. It works like a spreadsheet, compressing that repeated structure massively.
• ❌ SKIP IT FOR: Deeply nested, complex objects. If your JSON looks like a "tree" with many different levels and no repeating patterns, TOON might not save you much space compared to standard JSON.

Quick TOON Syntax Guide

TOON is simple. Here are the core concepts:

• Key-value pairs work just like YAML: key: value.
• Simple lists (arrays) use a hyphen - for each item.
• Tables are where TOON really shines. For a list of objects that all share the same keys, it uses a special table syntax:

  key[length]{header1,header2}:
    value1, value2

  That single header line replaces dozens of repeated keys. It's the main source of TOON's token efficiency.
• Nesting works through indentation — deeper data just gets indented further to the right.

TOON vs. Other Formats

Getting Started with TOON in Your Project

Using TOON in your code is straightforward with the official libraries. Here's a quick example in JavaScript/TypeScript:

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

const myData = {
  users: [
    { id: 1, name: "Alice", role: "admin" },
    { id: 2, name: "Bob", role: "editor" },
  ]
};

// Convert your object to a TOON string
const toonString = encode(myData);

// Now, include toonString in your LLM prompt
const prompt = `
  Analyze the following users:
  ${toonString}
`;

// Send the prompt to your LLM API...

Frequently Asked Questions