TOON Format Specification for LLM Token Optimization

TOON (Token-Oriented Object Notation) is a line-oriented, indentation-based text format that encodes the JSON data model with explicit structure and minimal quoting. It is designed to be a compact, deterministic representation of structured data, particularly well-suited for arrays of uniform objects and LLM prompts. Learn more in our introduction to TOON or see how it compares to JSON and TONL.

Introduction

TOON serves as a translation layer: produce data as JSON in code, encode to TOON for downstream consumption (e.g., LLM prompts), and decode back to JSON if needed. It aims to reduce token usage and improve readability for both humans and AI models.

Key Features

• Token Efficient: Designed to minimize token count for LLM contexts.
• Minimal Quoting: Strings are quoted only when necessary.
• Explicit Structure: Arrays declare their length and optional field lists upfront.
• Tabular Data: Optimized for arrays of uniform objects (tables).
• Deterministic: Produces consistent output for the same data.

Syntax

TOON uses indentation to denote structure and specific markers for arrays and objects.

Objects

Objects use indentation instead of braces. Keys are followed by a colon.

user:
  name: Alice
  role: admin

Arrays

Arrays declare their length in brackets [N].

Primitive Array (Inline):

colors[3]: red, green, blue

Array of Objects (Tabular):

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

Mixed Array (List):

items[2]:
  - first item
  - second item

Example

Here is a comparison of JSON and TOON:

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

Use Cases

• LLM Prompts: Reducing token costs and improving model comprehension of structured data. See our API cost optimization guide.
• Data Visualization: Compact representation of tabular data.
• Configuration: Readable configuration files without the verbosity of JSON or the ambiguity of YAML.

Getting Started

Ready to use TOON in your project? Check out our TypeScript/JavaScript installation guide to get started with the official TOON library. Try our free online converter or read the complete TOON specification guide.

Specification

• TOON Specification

{
  "content": "{\"key\": \"value\"}",  // Required: String content to convert
  "format": "json",                   // Optional: json, yaml, toml, xml (Auto-detected if omitted)
  "options": {                        // Optional: TOON encoding options
    "indent": 2
  }
}

{
  "content": "key: value",
  "detected_format": "json" // If auto-detected
}