Skip to main content

​
What is TOON?

Token-Oriented Object Notation (TOON) is a compact, human-readable encoding of the JSON data model that minimizes tokens and makes structure easy for models to follow. It’s designed specifically for LLM input as a drop-in, lossless representation of your existing JSON. TOON combines YAML’s indentation-based structure for nested objects with a CSV-style tabular layout for uniform arrays. This unique approach achieves CSV-like compactness while adding explicit structure that helps LLMs parse and validate data reliably.
TOON is not a replacement for JSON in your application code. Think of it as a translation layer: use JSON programmatically, and encode it as TOON for LLM input.

​
Why TOON?

AI is becoming cheaper and more accessible, but LLM tokens still cost money. Standard JSON is verbose and token-expensive, especially when dealing with structured data like arrays of objects.

Token Efficient

Save ~40% tokens compared to formatted JSON in mixed-structure benchmarks

More Accurate

Achieves 76.4% accuracy vs JSON’s 75% across 4 LLMs and 209 test questions

100% Lossless

Deterministic, bidirectional conversion between JSON and TOON

LLM-Friendly

Explicit [N] lengths and headers provide clear schema guardrails

​
Quick Comparison

See how TOON transforms verbose JSON into compact, readable format: 
{
  "context": {
    "task": "Our favorite hikes together",
    "location": "Boulder",
    "season": "spring_2025"
  },
  "friends": ["ana", "luis", "sam"],
  "hikes": [
    {
      "id": 1,
      "name": "Blue Lake Trail",
      "distanceKm": 7.5,
      "elevationGain": 320,
      "companion": "ana",
      "wasSunny": true
    },
    {
      "id": 2,
      "name": "Ridge Overlook",
      "distanceKm": 9.2,
      "elevationGain": 540,
      "companion": "luis",
      "wasSunny": false
    },
    {
      "id": 3,
      "name": "Wildflower Loop",
      "distanceKm": 5.1,
      "elevationGain": 180,
      "companion": "sam",
      "wasSunny": true
    }
  ]
}

​
Key Features

1

Minimal Syntax

Uses indentation instead of braces and minimizes quoting, giving YAML-like readability with CSV-style compactness.
2

Tabular Arrays

Uniform arrays of objects collapse into tables that declare fields once and stream row values line by line. Perfect for employee records, analytics data, and time-series.
3

JSON Data Model

Encodes the same objects, arrays, and primitives as JSON with deterministic, lossless round-trips. No information loss.
4

Multi-Language Ecosystem

Spec-driven implementations in TypeScript, Python, Go, Rust, .NET, and other languages. All implementations follow the official specification.

​
When to Use TOON

TOON excels with uniform arrays of objects (tabular data), where it achieves the greatest token savings:

Ideal For

  • Employee records, user lists
  • Time-series analytics data
  • E-commerce orders
  • Event logs with consistent structure
  • LLM prompts with structured data

Not Ideal For

  • Deeply nested configurations (0% tabular)
  • Non-uniform data structures
  • Pure flat tables (CSV is smaller)
  • Latency-critical local models
For deeply nested or non-uniform structures (tabular eligibility ≈ 0%), JSON-compact often uses fewer tokens. For semi-uniform arrays (~40-60% tabular), token savings diminish. See When to Use for detailed guidance.

​
Benchmark Results

TOON has been rigorously tested across 4 LLMs (Claude Haiku 4.5, Gemini 3 Flash, GPT-5 Nano, Grok 4.1 Fast) with 209 data retrieval questions:

​
Efficiency Ranking

TOON           ████████████████████   27.7 acc%/1K tok  │  76.4% acc  │  2,759 tokens
JSON compact   █████████████████░░░   23.7 acc%/1K tok  │  73.7% acc  │  3,104 tokens
YAML           ██████████████░░░░░░   19.9 acc%/1K tok  │  74.5% acc  │  3,749 tokens
JSON           ████████████░░░░░░░░   16.4 acc%/1K tok  │  75.0% acc  │  4,587 tokens
XML            ██████████░░░░░░░░░░   13.8 acc%/1K tok  │  72.1% acc  │  5,221 tokens
Efficiency score = (Accuracy % ÷ Tokens) × 1,000. TOON achieves 76.4% accuracy (vs JSON’s 75.0%) while using 39.9% fewer tokens.

​
Format Overview

TOON uses a simple, intuitive syntax:
  • Objects: YAML-style key-value pairs with indentation
  • Arrays: Declared with [N] length and optional {field1,field2} headers
  • Primitives: Strings, numbers, booleans, and null
  • Delimiters: Comma (default) or tab for even better efficiency
Example: All Data Types
name: Alice
age: 30
active: true
tags[3]: admin,developer,team-lead
projects[2]{id,name,status}:
  1,API Redesign,active
  2,Mobile App,completed

​
Media Type & File Extension

By convention, TOON files use:
  • File extension: .toon
  • Media type: text/toon (provisional)
  • Encoding: UTF-8 (default)
See the specification for normative details.

​
Next Steps

Quickstart

Install and encode your first data in 5 minutes

Format Overview

Learn the complete TOON syntax

Benchmarks

Deep dive into accuracy and token efficiency

API Reference

Explore all encode/decode functions

Build docs developers (and LLMs) love

Get started for freeTalk to us