TOON: Token-Efficient JSON for LLMs

  • 11/11/2025
  • 3-minute read

Are your LLM API costs creeping up as your prompts get longer and your datasets richer? TOON—Token-Oriented Object Notation—offers a practical way to reduce token usage without changing your workflow or sacrificing readability. This guide walks through what TOON is, why it’s useful, and how to start using it effectively in Python.

What is TOON?

TOON is a lightweight, LLM-aware data format designed to represent structured information using fewer tokens than JSON or YAML. It keeps things human-readable while reducing noise—especially for arrays of similar objects.

Key characteristics:

  • Indentation-based structure keeps formatting simple.
  • Tabular arrays let you define keys once, then list rows compactly.
  • Minimal quoting rules make text shorter without losing clarity.

A simple example:

JSON:

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

TOON:

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

The structure is the same, but the token count is typically 30–60% lower.

When TOON Works Best

Ideal use cases

  • Passing structured data into LLM prompts.
  • Reducing context size for classification, summarisation, or example-heavy tasks.
  • Storing or manipulating structured data in internal systems where you control both ends.

When not to use it

  • As a public interchange format where JSON is the expectation.
  • When consumers require strict tooling guarantees; TOON is still evolving.

Quick JavaScript Overview

The reference implementation—@toon-format/toon—includes encode and decode helpers.

npm install @toon-format/toon

Use it as you would other serialisers. The JS package is stable and works well for Node-based workflows.

Python: Installation and Basics

The Python implementation is available at https://github.com/toon-format/toon-python and on PyPI.

Install via PyPI:

pip install toon_format

Or install the latest version from GitHub:

pip install git+https://github.com/toon-format/toon-python.git

Basic usage:

from toon_format import encode, decode

data = {
    "users": [
        {"id": 1, "name": "Alice", "role": "admin"},
        {"id": 2, "name": "Bob", "role": "user"},
    ],
    "project": "LLM Optimisation"
}

toon_str = encode(data)
print(toon_str)

obj = decode(toon_str)
print(obj)

The output is a clean TOON block that can safely round-trip back to Python’s native structures.

The library also ships with a command-line tool:

# Convert JSON → TOON
toon input.json -o output.toon

# Convert TOON → JSON
toon data.toon -o output.json

Measuring Token Savings in Python

The Python package provides helper utilities for quick benchmarking.

from toon_format import estimate_savings, compare_formats

data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
result = estimate_savings(data)
print(f"Saves {result['savings_percent']:.1f}% tokens")

print(compare_formats(data))

Under the hood these functions rely on LLM tokenisers like tiktoken, giving side-by-side comparisons of JSON and TOON token footprints.

Using TOON in an LLM Prompt

Here’s a minimal example of embedding TOON in a prompt string:

from toon_format import encode

products = [
    {"id": 1, "name": "Acme Widget", "price": 9.99},
    {"id": 2, "name": "Gizmo", "price": 14.99},
]

prompt = (
    "Analyse the following products and provide a short summary:\n\n" +
    encode({"products": products}) +
    "\n"
)

print(prompt)

Swapping JSON for TOON typically cuts prompt tokens significantly, which means:

  • Lower API costs.
  • Faster response times.
  • More room in context windows.

Advanced Tips & Best Practices

  • Strict mode: Validate incoming TOON to guard against malformed indentation or length markers.
  • Key folding: Flatten deep structures (user.profile.name: Alice) to further reduce token usage.
  • Benchmark real payloads: Token savings vary—run a quick measurement before adopting widely.

Try TOON Live in the Browser

Want to experiment with TOON before using it in your workflows? These browser-based tools let you try it instantly:

  • TOON Playground: https://toon-playground.pages.dev
    Paste JSON on the left, see TOON on the right, and compare token counts.

  • JSON → TOON Converter / Validator: https://jsontoon.net
    Handy for quick conversions, validation, and testing how TOON handles your own payloads.

These tools are great for validating real-world savings and understanding how TOON structures data.

Further Resources

llmaijsontoontoken-efficiencyoptimisationpython