TOON Syntax Cheat Sheet: Every Rule on One Page

TOON encodes JSON using YAML-style indentation for nesting and CSV-style tables for uniform arrays of objects — with no braces, brackets, or repeated keys. This cheat sheet covers every rule: objects, simple lists, tabular arrays, delimiters, quoting, nesting, numbers, booleans, null, and edge cases, each paired with a JSON-to-TOON example.

For a deeper introduction, see What Is TOON? and the full TOON specification. To convert files now, use the free JSON-to-TOON converter.

TOON Syntax at a Glance

The table below maps each JSON construct to its TOON equivalent. Every rule is expanded with a code example in the sections that follow.

Rule 1: Key-Value Objects (No Braces)

The most fundamental rule: TOON objects drop all curly braces. Each key-value pair is written as key: value on its own line. The colon must be followed by at least one space when a value appears on the same line.

JSON

{
  "model": "gpt-5-nano",
  "temperature": 0.7,
  "stream": true
}

TOON

model: gpt-5-nano
temperature: 0.7
stream: true

Three lines; no opening or closing braces; no quote marks around the key or the bare-word string value. This alone saves roughly 30% of tokens on shallow objects.

Rule 2: Unquoted vs. Quoted Strings

Strings that are plain bare words do not need quotes, saving two tokens per value. Quotes are required in these situations:

• The value contains the active delimiter (comma by default).
• The value starts or ends with whitespace.
• The value could be mistaken for a number, boolean (true, false), or null.
• The value starts with a special character: -, [, #, or a double-quote.
• The value is an empty string.

JSON

{
  "status": "active",
  "label": "hello, world",
  "flag": "true",
  "empty": ""
}

TOON

status: active
label: "hello, world"
flag: "true"
empty: ""

active is bare because it is unambiguous. hello, world needs quotes because the comma is the default delimiter. true needs quotes to distinguish it from the boolean literal. An empty string is always quoted.

Rule 3: Simple Lists (Dash Syntax)

Primitive arrays and heterogeneous arrays of objects use list style: each item is prefixed with a dash and a space, indented under the key.

JSON

{
  "tags": ["featured", "new", "on-sale"]
}

TOON

tags:
  - featured
  - new
  - on-sale

No square brackets; no commas between items; no quotes on bare-word strings. Each item sits on its own line at 2-space indentation under the parent key.

Rule 4: Tabular Arrays of Objects (The Table Block)

This is TOON's signature feature. When an array contains objects that all share the same keys, TOON replaces the repeated structure with a single header line and comma-separated value rows — like a CSV embedded inside the document.

Header syntax: key[N]{field1,field2,...}:

• [N] — the number of rows, giving the LLM an explicit count to validate against.
• {field1,field2} — the schema: field names declared once for all rows.
• Each subsequent indented line is one row of comma-separated values.

JSON

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

TOON

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

The JSON version repeats id, name, and role three times each, plus six sets of braces and nine pairs of quotes around the keys. The TOON version declares the schema once and writes pure data rows. According to the official TOON benchmarks, flat uniform tables like this achieve 58.8% token reduction versus JSON (67,778 vs 164,452 tokens across the benchmark dataset).

Rule 5: Delimiters (Comma, Tab, Pipe)

TOON supports three delimiters for table row values. The delimiter is set globally for a document and applies to all table blocks within it.

When a value contains the active delimiter, wrap it in double quotes. Switching the delimiter to tab or pipe eliminates most quoting for text-heavy datasets.

Pipe-delimited example

orders[2]{id,note}:
  101 | Ships Monday, weather permitting
  102 | Back-ordered, arrives Friday

Both notes contain commas. Using pipe as the delimiter means neither value needs quoting.

Rule 6: Nesting via Indentation

TOON uses significant whitespace (2 spaces per level; tabs are forbidden) to express hierarchy. A key followed by a colon and no inline value means the next indented block is its value. This works to arbitrary depth.

JSON

{
  "user": {
    "name": "Alice",
    "address": {
      "city": "Berlin",
      "zip": "10115"
    }
  }
}

TOON

user:
  name: Alice
  address:
    city: Berlin
    zip: 10115

Every level of nesting removes one pair of braces from the JSON representation. You can place a table block inside a nested object at any depth — just maintain consistent 2-space indentation.

Rule 7: Numbers, Booleans, and Null

Scalar primitives use the same literals as JSON. No transformation required. Numbers follow standard JSON number format (integer, float, scientific notation). Booleans are lowercase true and false. Null is null.

JSON

{
  "count": 42,
  "ratio": 0.875,
  "large": 6.022e23,
  "active": true,
  "deleted": false,
  "parent": null
}

TOON

count: 42
ratio: 0.875
large: 6.022e23
active: true
deleted: false
parent: null

The only token savings here come from removing the surrounding object braces and key quotes. The primitive values themselves are token-identical to JSON.

Rule 8: Edge Cases

Values Containing the Delimiter

A table row value that contains the active delimiter must be quoted. The parser treats the first unquoted delimiter as a column separator.

products[2]{id,description}:
  1, "Red, White & Blue widget"
  2, Plain widget

Empty Arrays

An empty array is written as a list block with no items, or as a table header with zero rows.

# Empty list style
tags:

# Empty table style (zero rows declared)
users[0]{id,name}:

Mixed or Non-Uniform Arrays

When array items do not share the same set of keys — or when they are not all objects — TOON falls back to list style. Each item is written as a dash-prefixed entry, and complex items are indented beneath it.

JSON

{
  "items": [
    {"type": "text", "value": "hello"},
    {"type": "image", "url": "img.png", "width": 800}
  ]
}

TOON (list fallback — fields differ between items)

items:
  - type: text
    value: hello
  - type: image
    url: img.png
    width: 800

This is still more compact than JSON, but it does not get the full table-style savings. For best results, normalize your data to uniform schemas before converting — see TOON best practices for guidance.

Comments

TOON supports inline and standalone comments with #. Comments are stripped during parsing and have no JSON equivalent. They are useful for annotating prompts before sending to an LLM.

# Retrieved from cache at 2026-06-03T09:00Z
config:
  timeout: 5000   # milliseconds
  retries: 3

Complete Example: JSON vs. TOON Side by Side

The following example combines objects, a table array, nesting, and scalars — the full range of TOON constructs in a single document.

JSON (89 tokens)

{
  "service": "recommendations",
  "version": 2,
  "active": true,
  "config": {
    "max_results": 10,
    "threshold": 0.75
  },
  "users": [
    {"id": 1, "name": "Alice", "tier": "pro"},
    {"id": 2, "name": "Bob",   "tier": "free"},
    {"id": 3, "name": "Carol", "tier": "pro"}
  ]
}

TOON (approx. 54 tokens — ~39% fewer)

service: recommendations
version: 2
active: true
config:
  max_results: 10
  threshold: 0.75
users[3]{id,name,tier}:
  1, Alice, pro
  2, Bob, free
  3, Carol, pro

Across a real-world benchmark of 5,016 LLM calls, TOON achieved 39.9% fewer tokens than JSON while maintaining 76.4% retrieval accuracy (versus JSON's 75.0%) — a meaningful accuracy-per-token improvement. Full methodology and per-dataset breakdowns are at toonformat.dev/guide/benchmarks.

Quick Reference: When to Use Each Construct

For the complete grammar in ABNF notation and parser implementation notes, see the TOON specification. For interactive conversion, use /docs/toon or paste your JSON directly into the converter.

Frequently Asked Questions