WHEN CREATED:

Token-Oriented Object Notation (TOON) is a very recent innovation, with its initial public projects and format definition emerging around late 2024 / early 2025. This timing is crucial, as it places TOON's creation squarely in the era where Large Language Model (LLM) technology became mainstream and its associated operational costs became a primary concern for businesses. The format was designed to be a direct, practical solution to this problem: Standard JSON, which was never designed with token efficiency in mind, wastes a significant number of tokens on redundant characters (quotes, braces, commas, and repeated keys). TOON was specifically engineered as a lossless, drop-in replacement for JSON data when used as an LLM prompt input. Crucially, the TOON format and its reference implementations are released under the MIT License, ensuring it is open-source, easily accessible, and free for both commercial and private use, allowing developers to immediately benefit from its efficiency and send the same information with significantly fewer tokens. The Problem: JSON is Too "Chatty"

AI is becoming cheaper and more accessible, and while larger context windows allow us to feed LLMs more data, LLM tokens still cost money. The fundamental issue is that standard JSON is verbose and token-expensive. It was designed for machine-to-machine communication, not for token-efficient LLM input. Every piece of punctuation—the braces, brackets, colons, and repeated quotation marks—consumes tokens without adding unique, meaningful information. For example, look at a small user array in standard JSON:

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

// Number of token : 50

JSON relies heavily on specific characters to define its structure. These characters must be included in your prompt and consume tokens, but they don't add unique information about your users (Alice and Bob).

In your small example, the core data is 1, Alice, admin, 2, Bob, user. Everything else is just formatting that you pay for

This "chatty" nature of JSON directly translates to three main penalties for the user:

1. Higher API Costs: You are paying the LLM provider for every redundant token. If 30-60% of your prompt is just JSON syntax, your bill is unnecessarily inflated.

2. Context Window Limits: Every wasted token takes up valuable space in the LLM's context window (the maximum text it can process). This means you can send the model fewer actual users or products before you hit the limit and have to split your request.

3. Slower Latency: The LLM has to process more tokens, leading to slower response times.

The TOON Solution: Declare Once, Stream Data:

The core brilliance of Token-Oriented Object Notation (TOON) lies in its philosophy of "Declare Once, Stream Data," which is achieved by borrowing the best ideas from formats like YAML (for indentation) and CSV (for tabular data) to create a final format that is both human-readable and hyper-efficient for LLM processing. This efficiency is realized by eliminating the repetitive redundancy that plagues JSON, especially with uniform lists; instead of forcing developers to repeat field names for every single item, TOON simply declares the entire data structure (including keys and item count) only one time, and then allows the data values to be cleanly streamed in a compact, row-by-row fashion

The difference is staggering. In the TOON snippet (which contains approximately 19 tokens), the structural information is handled by a single header line: users[2]{id,name,role}:. This line efficiently communicates:

1. Object Name: A list called "users".

2. Explicit Length: It contains 2 items ([2]).

3. Keys: The keys for each item are "id", "name", and "role".

After this single declaration, it simply streams the comma-separated values for each row: 1,Alice,admin and 2,Bob,user

The Payoff: Massive Token Savings

The efficacy of Token-Oriented Object Notation (TOON) is clearly demonstrated by its performance benchmarks. The project's own testing confirms that these are not trivial savings; they translate directly into a significant reduction in operational costs. For instance, in a test involving 100 GitHub repository objects, TOON delivered an impressive token reduction of 42.3% compared to standard JSON. The savings were even more dramatic when applied to a daily web analytics dataset, where it achieved a token reduction of nearly 58.9%. When developers are making hundreds or even thousands of Large Language Model (LLM) calls per day, this massive efficiency gain quickly compounds, making TOON an essential tool for managing API expenses and scaling LLM-powered applications affordably.

But Can LLMs Actually Understand It?

This is the most critical question. What's the point of saving tokens if the model can't retrieve the data?

The answer is a definitive yes, and in many cases, Large Language Models (LLMs) can process TOON data as reliably as, or even better than, standard JSON. The reason for this success lies in TOON's smart design, which avoids completely reinventing the wheel. Instead, it leverages structural patterns that LLMs were extensively trained on: the indentation-based structure of YAML to define hierarchy and the tabular nature of CSV for lists. By relying on these familiar, predictable formats, TOON minimizes ambiguity and allows the LLM to apply its existing parsing capabilities, demonstrating that token savings do not need to compromise model comprehension.

Furthermore, TOON incorporates key LLM-friendly "guardrails" that aid in accurate processing. For instance, notations like users[2] explicitly declare the expected number of items in an array. This is a critical feature because it helps prevent common LLM issues such as truncating a list or hallucinating extra objects, which can often happen when JSON objects are deeply nested or lengthy. By removing the visual and token "noise" of repetitive JSON punctuation (like quotes and braces) and replacing it with clean, simple tabular structures, TOON allows the model to focus its attention entirely on the meaningful data—the keys and values—leading to high accuracy in data retrieval tasks, even while using 40-60% fewer tokens.

Ultimately, the goal is not just token efficiency but reliable data exchange. Benchmarks have shown that TOON performs strongly in data extraction tasks, proving that its compact design is highly predictable and easily understandable by the current generation of large language models.

Accuracy between four models in Toon

How to Get Started & INSTALL

Getting started with Token-Oriented Object Notation (TOON) is designed to be straightforward—it's essentially a drop-in replacement for JSON.stringify() when preparing data for your LLM prompts.

# npm
npm install @toon-format/toon

# pnpm
pnpm add @toon-format/toon

# yarn
yarn add @toon-format/toon

Example Code

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

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

console.log(encode(data))
// users[2]{id,name,role}:
//   1,Alice,admin
//   2,Bob,user

CLI

Command-line tool for converting between JSON and TOON formats.

The toon Command Line Interface (CLI) is designed for flexibility and ease of use, allowing developers to seamlessly integrate TOON conversion into their terminal workflows. The tool is smart enough to handle input data from two sources: directly from a specified file or via standard input (stdin), where data is piped directly from the output of another command (by omitting the input argument or using a single hyphen -). For simple file-based conversions, the tool offers auto-detection: it automatically knows to encode (JSON to TOON) if the input file ends in .json and to decode (TOON to JSON) if the input file ends in .toon.

Examples:

# Encode JSON to TOON (auto-detected)
npx @toon-format/cli input.json -o output.toon

# Decode TOON to JSON (auto-detected)
npx @toon-format/cli data.toon -o output.json

# Output to stdout
npx @toon-format/cli input.json

# Pipe from stdin (no argument needed)
cat data.json | npx @toon-format/cli
echo '{"name": "Ada"}' | npx @toon-format/cli

# Explicit stdin with hyphen (equivalent to above)
cat data.json | npx @toon-format/cli -

# Decode from stdin
cat data.toon | npx @toon-format/cli --decode

Options

Json To Toon Examples

Imagine you have a simple list of people with their names and ages. In JSON, it would look something like this:

[
  {
    "name": "Alex Johnson",
    "age": 30
  },
  {
    "name": "Maria Rodriguez",
    "age": 25
  },
  {
    "name": "Ben Carter",
    "age": 42
  },
  {
    "name": "Samantha Lee",
    "age": 19
  },
  {
    "name": "David Chen",
    "age": 55
  }
]

Convert it into toon using

npx @toon-format/cli input.json

Output

[5]{name,age}:
  Alex Johnson, 30
  Maria Rodriguez, 25
  Ben Carter, 42
  Samantha Lee, 19
  David Chen, 55

If You want to save the output in a file the use this command

npx @toon-format/cli input.json -o output.toon

Toon To Json Examples

npx @toon-format/cli --decode data.toon -o output.json

This command successfully takes your compact TOON data (data.toon) and reconstructs the verbose, standard JSON structure into a new file named output.json.

USING TOON FILE WITH LLM MODEL

We’ve seen the token savings and readability of the TOON format. Now, let’s bring it all together with a practical example showing exactly how a Node.js application uses that compact data to dynamically build a highly specific prompt for a Large Language Model (LLM).

LLM Model used : Xenova/gpt2 ( https://huggingface.co/Xenova/gpt2)

Toon file

What does it do: The LLM Model genrates a story about the famous dish of a given city if it’s data is store inside the Toon file

[52]: # The array length (52 entries total)
  - city: Mumbai
    state: Maharashtra
    famous_dish: Vada Pav
    alternates[3]: Pav Bhaji,Misal Pav,Bhel Puri
  - city: Delhi
    state: National Capital Territory
    famous_dish: Chole Bhature
    alternates[3]: "Chaat (Gol Gappe, Aloo Tikki)",Parathe,Butter Chicken
  - city: Kolkata
    state: West Bengal
    famous_dish: Rosogolla (Mishti Doi)
    alternates[3]: Kathi Rolls,Phuchka,Fish Curry (Machher Jhol)
  # ...  other entries ...

Code using toon file with LLM model

import { pipeline } from '@huggingface/transformers';
import * as fs from 'fs'; 
import * as path from 'path'; 

function buildCityMap(data) {
    if (!data) return null;
    
    if (!Array.isArray(data) && typeof data === 'object') {
        const map = {};
        for (const k of Object.keys(data)) {
            map[k.trim().toLowerCase()] = data[k];
        }
        return map;
    }

    const map = {};
    if (Array.isArray(data)) {
        for (const entry of data) {
            if (!entry || !entry.city) continue;
            const normalized = entry.city.trim().toLowerCase();
            map[normalized] = entry;
        }
    }
    return map;
}

function loadToonData() {
    const TOON_PATH = path.join(process.cwd(), 'output.toon');
    try {
        if (!fs.existsSync(TOON_PATH)) return null;
        const text = fs.readFileSync(TOON_PATH, 'utf8');
        const lines = text.split(/\r?\n/);
        const entries = [];
        let current = null;

        for (let raw of lines) {
            const line = raw.trim();
            const mCity = line.match(/^-?\s*city:\s*(.+)$/i);
            if (mCity) {
                if (current) entries.push(current);
                current = { city: mCity[1].replace(/^"|"$/g, '').trim() };
                continue;
            }
            if (!current) continue;

            const mState = line.match(/^state:\s*(.+)$/i);
            if (mState) {
                current.state = mState[1].replace(/^"|"$/g, '').trim();
                continue;
            }

            const mDish = line.match(/^famous_dish:\s*(.+)$/i);
            if (mDish) {
                current.famous_dish = mDish[1].replace(/^"|"$/g, '').trim();
                continue;
            }

            const mAlt = line.match(/^alternates(?:\[\d+\])?:\s*(.+)$/i);
            if (mAlt) {
                const list = mAlt[1]
                    .split(',')
                    .map(s => s.replace(/^"|"$/g, '').trim())
                    .filter(Boolean);
                current.alternates = list;
                continue;
            }
        }

        if (current) entries.push(current);
        return entries;
    } catch (err) {
        console.error(`Could not read/parse output.toon: ${err.message}`);
        return null;
    }
}

const toonData = loadToonData();

// Build cityMap from toonData only
const cityMap = buildCityMap(Array.isArray(toonData) ? toonData : []);

// --- 2. Main Execution Function ---

async function runTextGenerationWithContext() {
    
    if (!cityMap) {
        console.error('No city data available (output.toon missing or empty).');
        return; // Stop if data loading failed
    }
    
    // --- SIMULATE USER INPUT ---
    // In a real app, you would use a library like 'readline' to get input.
    const userCity = 'Delhi'; // <--- Change this to test different cities
    console.log(`\nUser's selected city: **${userCity}**\n`);

    // Use a normalized, case-insensitive lookup into the city map
    const normalizedKey = userCity.trim().toLowerCase();
    let initialPrompt;

    // --- City Lookup and Prompt Customization ---
    const cityEntry = cityMap[normalizedKey];
    if (cityEntry) {
        const food = cityEntry.famous_dish;
        const state = cityEntry.state;
        const displayCity = cityEntry.city || userCity;

        // Custom prompt using the found food item
        console.log(`Found famous dish: **${food}** from ${state}.`);
        initialPrompt = `Once upon a time there was a developer who visited ${displayCity}. They were so excited to try the famous ${food} that they`;
    } else {
        // Fallback prompt if city is not in the JSON file
        console.log(`City ${userCity} not found in food data. Using a generic prompt.`);
        initialPrompt = 'Once upon a time there was a developer who';
    }

    // --- 3. Hugging Face Pipeline ---

    // Generate prompt message
    console.log(`Generating text with prompt: "${initialPrompt}"`);

    // Initialize the pipeline while suppressing any noisy logs from
    // the underlying runtime (e.g., dtype warnings). We temporarily
    // silence console methods during initialization and restore them
    // immediately after to avoid hiding other messages.
    let generator;
    const origLog = console.log;
    const origWarn = console.warn;
    const origError = console.error;
    try {
        console.log = () => {};
        console.warn = () => {};
        console.error = () => {};
        generator = await pipeline('text-generation', 'Xenova/gpt2');
    } finally {
        console.log = origLog;
        console.warn = origWarn;
        console.error = origError;
    }

    const output = await generator(initialPrompt, {
        max_new_tokens: 50,
    });

    // --- 4. Output Result ---
    
    console.log('\n--- Generated Story ---\n');
    console.log(output[0].generated_text);
    console.log('\n-----------------------\n');
}

runTextGenerationWithContext();

The provided JavaScript code sets up a complete process for contextualizing a Large Language Model (LLM) prompt using local TOON data. It first defines functions (loadToonData and buildCityMap) to read the compact TOON file (output.toon)—which efficiently stores city and food data—and converts it into a fast-lookup map. The main function, runTextGenerationWithContext, simulates user city input (e.g., 'Delhi'), uses the TOON map to retrieve a specific fact (e.g., 'Chole Bhature'), and then injects that fact into the starting phrase of a story. Finally, it uses the locally running, optimized Xenova/gpt2 model (via Hugging Face Transformers.js) to generate a customized and highly relevant story continuation, demonstrating how TOON enables efficient data context for high-quality, local LLM output.

Why Toon is not better in every scenario

TOON files are not always good for every model because large language models do not truly “understand” data formats logically; they rely on patterns they have seen frequently during training. While TOON is more compact and token-efficient, many models have not been extensively trained on this notation, so they struggle to reliably infer structure, hierarchy, and field boundaries from it. In contrast, JSON and CSV are extremely common across web data, documentation, APIs, logs, and training corpora, making their syntax and structure deeply familiar to most models. JSON provides explicit hierarchy and key–value clarity, which helps models preserve relationships between data fields, while CSV offers a simple, predictable, flat structure that models can parse with high confidence. As a result, even though TOON uses fewer tokens and contains the same information, models often perform better with JSON or CSV because familiarity, structural cues, and training exposure matter more than compactness for accurate interpretation and reasoning.

CONCLUSION:

TOON is a practical, drop‑in way to slash LLM token spend without sacrificing structure or accuracy. By declaring schema once and streaming compact rows, it routinely cuts prompt size by 40–60%, letting you fit more real data into the same context window, speed up responses, and lower costs. Just as important, its YAML‑like hierarchy and CSV‑style tables make it easy for models to parse reliably, while length declarations add guardrails against truncation or hallucinated items.

If your workloads include uniform arrays of objects—catalogs, profiles, telemetry, analytics—TOON will likely pay for itself on day one. Keep JSON for highly irregular, deeply nested edge cases; use TOON for the vast middle where structure is consistent and volume is high.

Sources

• GitHub repo

• Hugging Face model (example LLM)

• Additional GitHub resources

• Chase’s write‑up