Documentation

Complete guide to TOON format and its implementation

What is TOON?

TOON (Token-Oriented Object Notation) is a compact, human-readable data encoding format designed specifically for LLM input.

Key characteristics:

  • •Minimizes tokens
  • •Makes data structure easy for models to follow
  • •Combines YAML's indentation with CSV-style tabular layout
  • •Optimized for uniform arrays of objects

JSON (verbose)

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

TOON (compact)

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

Why TOON?

TOON reduces data representation verbosity compared to standard JSON, making it ideal for LLM applications where token efficiency matters.

Design Goals

  • •Maximize compactness for uniform object arrays
  • •Remain lossless and deterministic
  • •Keep parsing simple
  • •Provide validation guardrails

When to Use TOON

Best for:

  • •Uniform arrays of objects
  • •LLM prompts requiring deterministic, minimally quoted text
  • •Scenarios needing built-in data validation

When Not to Use TOON

Avoid for:

  • •Deeply nested structures
  • •Semi-uniform arrays
  • •Pure tabular data
  • •Latency-critical applications

Benchmark

TOON Documentation Benchmark Comparison
TOON
26.9│73.9% acc│2,744 tokens
JSON compact
22.9│70.7% acc│3,081 tokens
YAML
18.6│69.0% acc│3,719 tokens
JSON
15.3│69.7% acc│4,545 tokens
XML
13.0│67.1% acc│5,167 tokens

What's Being Measured

Benchmark evaluation process:

  • •209 questions across 6 formats
  • •4 different AI models tested
  • •5,016 total LLM calls
  • •GPT-5 o200k_base tokenizer

Key results:

  • •73.9% accuracy (vs 69.7% for JSON)
  • •39.6% fewer tokens vs JSON
  • •Up to 60.7% reduction for flat data

Installation

TypeScript Library

Install via package managers:

npm install @toon-format/toon
pnpm add @toon-format/toon
yarn add @toon-format/toon

CLI Installation

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

First Example

Encoding data with TOON:

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

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

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

Syntax Cheatsheet

Objects

JSON

{ "id": 1, "name": "Ada" }

TOON

id: 1
name: Ada

Primitive Arrays

JSON

{ "tags": ["foo", "bar", "baz"] }

TOON

tags[3]: foo,bar,baz

Tabular Arrays

JSON

{
  "items": [
    { "id": 1, "qty": 5 },
    { "id": 2, "qty": 3 }
  ]
}

TOON

items[2]{id,qty}:
  1,5
  2,3

Quoting Rules

Strings must be quoted if they:

  • •Are empty
  • •Have leading/trailing whitespace
  • •Equal true, false, or null
  • •Look like numbers
  • •Contain special characters or active delimiter

API Reference

encode(value, options?)

Converts JSON-serializable values to TOON format.

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

const data = {
  name: 'Alice',
  age: 30,
  hobbies: ['reading', 'coding']
}

const toonString = encode(data)
console.log(toonString)

Options:

  • indent - Spaces per indentation level (default: 2)
  • delimiter - Array/row delimiter (default: ',')
  • keyFolding - Key folding strategy
  • flattenDepth - Maximum folding segments

encodeLines(value, options?)

Streams TOON encoding line-by-line. Useful for large datasets and memory-efficient processing.

Supports same options as encode()

decode(input, options?)

Converts TOON-formatted strings back to JavaScript values.

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

const toonString = `name: Alice
age: 30
hobbies[2]: reading coding`

const data = decode(toonString)
console.log(data)

Options:

  • indent - Expected indentation spaces
  • strict - Validation mode (default: true)
  • expandPaths - Path expansion strategy

CLI Tool

TOON provides a command-line interface for quick conversions:

Convert JSON to TOON

toon encode input.json -o output.toon

Convert TOON to JSON

toon decode input.toon -o output.json

Show token statistics

toon encode input.json --stats

Official Implementations

TypeScript

Stable

Python

In Development

Go

In Development

Rust

In Development

.NET

In Development

Dart

In Development

Community Implementations

Additional implementations available in: Apex, C++, Clojure, Crystal, Elixir, Gleam, Java, Kotlin, PHP, Ruby, Swift, and more.

When implementing TOON in other languages, please follow the specification to ensure compatibility across implementations.

Ready to Start Using TOON?

Try our free online converter to see how much you can save on LLM token usage

Try Converter