Getting Started with TOON: A Developer's Guide

🚀 Tutorial • • 12 min read

Welcome to TOON — Token-Oriented Object Notation. If you're a developer sending structured JSON data into LLM prompts (agent context, RAG results, chatbot memory, API responses) and want to cut token usage without losing readability, you're in the right place. TOON's published spec and benchmarks report roughly 42.6% fewer tokens than equivalent JSON, with comparable-or-better LLM retrieval accuracy (72.2% vs JSON's 71.4%). This guide walks you through the real TOON syntax step by step.

🎯 What You'll Learn

  • • Basic TOON key-value syntax
  • • Nested objects and indentation rules
  • • The tabular array format — TOON's signature space-saving feature
  • • How to convert JSON to TOON and back
  • • When TOON falls back to an indexed array form
  • • Real use cases for TOON in LLM prompts and agent workflows

📝 Understanding TOON Syntax

TOON uses a clean, indentation-based syntax that's designed to be immediately readable while using far fewer tokens than JSON. Let's start with the basics and build up to the format's signature feature: tabular arrays.

Basic Key-Value Pairs

The simplest TOON structure consists of key-value pairs, one property per line, with no quotes needed for simple strings, numbers, booleans, or null:

TOON Format

id: 4821
name: Ada Lovelace
role: Engineer
active: true
manager: null

Equivalent JSON

{
  "id": 4821,
  "name": "Ada Lovelace",
  "role": "Engineer",
  "active": true,
  "manager": null
}

💡 Key Differences:

  • • No quotes needed around simple strings
  • • No commas between properties
  • • No curly braces required
  • • Each property gets its own line

Nested Objects

TOON uses 2-space indentation to represent nested objects — no braces needed. Here's a user record with a nested address:

TOON Format

user:
  name: Ada Lovelace
  role: Engineer
  address:
    city: Berlin
    country: DE
    postal_code: 10115

Equivalent JSON

{
  "user": {
    "name": "Ada Lovelace",
    "role": "Engineer",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "postal_code": 10115
    }
  }
}

Arrays of Primitives

A flat array of primitive values collapses to one line. The number in brackets is the item count, which TOON uses to help an LLM verify it "saw" every element:

TOON Format

tags[3]: backend,api,production
scores[4]: 88,92,79,95

Equivalent JSON

{
  "tags": ["backend", "api", "production"],
  "scores": [88, 92, 79, 95]
}

Tabular Arrays — TOON's Signature Feature

This is where TOON saves the most tokens compared to JSON. When an array holds uniform objects (same fields in every item), TOON writes the field names once in a header, then lists each row as comma-separated values in that exact order — no repeated key names per row. The header format is key[N]{field1,field2,...}:, where N is the row count:

TOON Format

users[3]{id,name,role,email}:
  1,Ada Lovelace,Engineer,ada@example.com
  2,Grace Hopper,Architect,grace@example.com
  3,Alan Turing,Researcher,alan@example.com

Equivalent JSON

{
  "users": [
    { "id": 1, "name": "Ada Lovelace", "role": "Engineer", "email": "ada@example.com" },
    { "id": 2, "name": "Grace Hopper", "role": "Architect", "email": "grace@example.com" },
    { "id": 3, "name": "Alan Turing", "role": "Researcher", "email": "alan@example.com" }
  ]
}

Notice how each field name in the JSON version ("id", "name", etc.) is repeated once per object. TOON states it once in the header and never again — that repetition is exactly what TOON's tabular form eliminates, which is the main source of its token savings on list-heavy data like API responses, database query results, and search results passed into an LLM prompt.

Values that contain a comma, a colon, or leading/trailing whitespace get double-quoted so the row can still be split correctly:

TOON Format

notes[2]{id,text}:
  1,"Ships Monday, pending approval"
  2,"Blocked: waiting on vendor"

Arrays that are not uniform — mixed types, or objects with different shapes — can't use the tabular header. TOON falls back to an indexed, expanded form instead:

TOON Format (fallback for mixed data)

events[2]:
  [0]: "deployment started"
  [1]:
    type: error
    code: 500

🔄 Converting Between JSON and TOON

The easiest way to start with TOON is to convert JSON you already have. This site's converter does it instantly and reversibly — you can go from JSON to TOON and back to JSON with no data loss.

Using the Online Converter

Try the bidirectional converter on the homepage or the dedicated JSON to TOON converter tool. Paste JSON in, get TOON out — or paste TOON in to get JSON back.

🚀 Quick Start:

  1. Copy your JSON data (an API response, a database query result, etc.)
  2. Paste it into the converter
  3. Click "Convert to TOON"
  4. Review the tabular arrays in the output
  5. Paste the TOON output straight into your LLM prompt

Manual Conversion Guidelines

For a better feel for the format, here's how to convert JSON to TOON by hand:

Step 1: Drop Braces and Brackets

Remove the object braces { } — indentation replaces them. Keep array brackets only as the [N] count marker.

Step 2: Drop Unnecessary Quotes

Remove quotes from key names and plain string values. Keep quotes only for values containing a comma, a colon, or leading/trailing whitespace, e.g. note: "value, with comma".

Step 3: Drop Commas Between Lines

Commas only remain inside inline arrays and tabular rows — remove them between key-value lines.

Step 4: Indent Nested Objects

Use consistent 2-space indentation for each level of nesting.

Step 5: Convert Arrays

Primitive arrays become key[N]: v1,v2,v3. Arrays of uniform objects become a tabular header key[N]{field1,field2}: followed by comma-separated rows.

🏗️ Building Complex Structures

Now let's combine everything into one realistic example: an API response for a project management tool that you might drop straight into an LLM prompt so an agent can answer questions about it.

Complete Example: Project API Response

project.toon

project:
  id: PRJ-1042
  name: Website Redesign
  status: in_progress
  created: 2024-01-15
  tags[3]: frontend,design,q1-2024

owner:
  id: 7
  name: Priya Shah
  email: priya@example.com

members[3]{id,name,role,email}:
  1,Ada Lovelace,Engineer,ada@example.com
  2,Grace Hopper,Architect,grace@example.com
  3,Alan Turing,Researcher,alan@example.com

tasks[4]{id,title,assignee_id,status,hours}:
  101,Set up CI pipeline,1,done,6
  102,Design new homepage,3,in_progress,14
  103,"Migrate database, add indexes",2,in_progress,20
  104,Write API docs,1,todo,5

budget:
  currency: USD
  total: 50000
  spent: 12500
  remaining: 37500

📋 Key Features Demonstrated:

  • • Plain key-value pairs at the top level (status, created)
  • • A nested object for owner
  • • An inline primitive array for tags[3]
  • • Two tabular arrays (members and tasks) — each field name written once
  • • A quoted value in row 103 because its task title contains a comma

🛠️ Using TOON in LLM Applications

TOON isn't a file format you check into version control instead of JSON — it's a serialization you generate right before a prompt is sent, wherever token count matters. Two common patterns:

🔎 RAG and Search Results

When you retrieve a list of documents or search hits to stuff into context, convert the array to TOON's tabular form before inserting it into the prompt. Uniform records (id, title, score, snippet) are exactly the shape tabular arrays are built for.

🤖 Agent Tool Outputs

When a tool call returns a JSON array (API records, database rows, log entries), convert the result to TOON before appending it to the agent's context window instead of feeding back raw JSON.

Do's and Don'ts

✅ Do's

  • Use consistent 2-space indentation
  • Use the tabular form for uniform arrays of objects
  • Quote any value containing a comma, colon, or leading/trailing whitespace
  • Double-check the [N] count matches the actual number of rows/items
  • Keep related fields grouped together

❌ Don'ts

  • Don't mix tab and space indentation
  • Don't use the tabular header on non-uniform objects — use the indexed fallback instead
  • Don't forget to quote a comma-containing value in a tabular row
  • Don't leave the item count out of sync with the row count
  • Don't nest nest more than a few levels deep — flatten where you can

Tooling

You don't need to hand-write TOON in production. Use this site's JSON to TOON converter for one-off conversions, or generate TOON programmatically with a library from the official spec repository, which lists community encoders/decoders for several languages.

⚡ Getting the Most Token Savings

TOON's published benchmarks show roughly 42.6% fewer tokens than equivalent JSON, but how much you actually save depends on how you shape the data before conversion.

Where Savings Come From

  • Tabular arrays: the biggest win — field names are written once instead of once per row
  • No repeated braces/brackets: indentation replaces most punctuation
  • Inline primitive arrays: a whole list on one line instead of one line per item
  • Fewer quotes: quoting only when a value actually needs it

Shaping Data for Tabular Form

  • Keep object shape uniform: same fields, same order, across every item in the array
  • Flatten one level of nesting in list items where practical, so more arrays qualify for tabular form
  • Consistent field naming: stick to one casing convention
  • Only include fields the LLM actually needs in the prompt

🐛 Common Pitfalls and How to Avoid Them

Here are common mistakes developers make when starting with TOON and how to avoid them:

❌ Inconsistent Indentation

Problem: Mixing tabs and spaces, or varying the indent width between levels, breaks parsing.

Solution: Use 2 spaces per level, consistently, throughout the document.

⚠️ Forgetting to Quote Values with Commas or Colons

Problem: In a tabular row, an unquoted comma inside a value gets read as a new column, silently corrupting the row.

Solution: Quote any value with a comma, colon, or leading/trailing whitespace: note: "Ships Monday, pending approval"

ℹ️ Using the Tabular Header on Non-Uniform Data

Problem: If array items don't all share the same fields, a tabular header {field1,field2} can't represent every row correctly.

Solution: Only use tabular form for uniform object arrays. For mixed shapes or types, fall back to the indexed [0]:, [1]: form.

✅ Best Practice: Let the Count Guard the Data

Instead of: Manually writing TOON and losing track of how many rows you added.

Use: A converter to generate TOON from JSON — the [N] count is then always correct, and an LLM reading it can double-check it saw every row.

🚀 Next Steps and Resources

You now have a solid foundation in TOON syntax. Here's how to keep going:

📚 Learning Resources

🛠️ Tools

🎯 Pro Tip: Start with Your Biggest List

Don't try to convert your entire prompt pipeline at once. Find the single largest array of uniform records you're currently sending as JSON — search results, API records, log rows — convert just that to TOON's tabular form, and measure the token difference. That's usually where the savings are biggest and easiest to prove out.

💡 Quick Reference Cheat Sheet

TOON Format Quick Reference

# Basic key-value pairs
id: 4821
name: Ada Lovelace
active: true
manager: null

# Nested objects (2-space indent, no braces)
user:
  name: Ada Lovelace
  address:
    city: Berlin
    country: DE

# Arrays of primitives (inline)
tags[3]: backend,api,production

# Tabular arrays of uniform objects (the signature feature)
users[2]{name,role,email}:
  Ada Lovelace,Engineer,ada@example.com
  Grace Hopper,Architect,grace@example.com

# Quoted values (comma, colon, or leading/trailing whitespace)
note: "Ships Monday, pending approval"
ratio: "3:2"

# Non-uniform arrays fall back to indexed expanded form
events[2]:
  [0]: "deployment started"
  [1]:
    type: error
    code: 500
Try the Converter Read Full Documentation Explore More Articles

Try Converting JSON to Toon

Paste some JSON below to see it converted to Toon format:

🚀

Developer Experience Team

Experts in developer tools and workflow integration