TOON Syntax Rules

A complete guide to the TOON format specification.

Basic Primitives

Strings

Strings can be written with or without quotes:

name: Alice
title: Senior Engineer
message: "Hello, World!"

Quote when:

  • String contains special characters (:, ,, [, ], {, })
  • String starts with a number
  • String is a reserved word (true, false, null)

Numbers

Numbers are written as-is:

age: 30
price: 19.99
count: 1000000

Booleans

Use lowercase:

active: true
deleted: false

Null

Use lowercase:

value: null

Objects

Objects use indentation-based nesting:

user:
  id: 1
  name: Alice
  email: alice@example.com

Nested objects:

company:
  name: ACME Corp
  address:
    street: 123 Main St
    city: Boulder
    state: CO
    zip: 80301

Arrays

Simple Arrays

Inline, comma-separated with length declaration:

tags[3]: javascript,typescript,react
numbers[5]: 1,2,3,4,5

Arrays of Objects (Tabular Format)

The most powerful feature of TOON:

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

Syntax breakdown:

  • users - Array name
  • [2] - Length (number of items)
  • {id,name,role} - Field names
  • Indented rows with comma-separated values

Mixed Arrays

Arrays with different value types:

mixed[4]: 1,"text",true,null

Delimiters

Comma (Default)

Standard delimiter for arrays:

items[3]: apple,banana,cherry

Tab Delimiters

For maximum token efficiency:

data[2]{id	name	value}:
  1	Alice	100
  2	Bob	200

Use tab delimiters with the encode() function to generate tab-separated TOON.

Complex Example

Combining all features:

context:
  task: Favorite Hikes
  location: Boulder
  season: spring_2025
friends[3]: ana,luis,sam
hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:
  1,Blue Lake Trail,7.5,320,ana,true
  2,Ridge Overlook,9.2,540,luis,false
  3,Wildflower Loop,5.1,180,sam,true
metadata:
  created: 2025-01-15
  version: 1.0

Indentation Rules

  • Use 2 spaces for each level of nesting (default)
  • Tabs are allowed but not recommended for indentation
  • Be consistent within a document

Special Characters

Characters that need quoting in strings:

  • : - Colon (key-value separator)
  • , - Comma (array delimiter)
  • [ ] - Brackets (array length)
  • { } - Braces (field headers)
  • # - Hash (comments, if supported)

Comments

TOON does not currently support comments in the specification. Remove comments before converting.

Best Practices

  1. Use tabular format for uniform arrays - Maximum token savings
  2. Declare array lengths - Helps models validate data
  3. Be consistent with quoting - Only quote when necessary
  4. Keep field names short - They're repeated in the header
  5. Use tab delimiters for production - Extra ~5-10% token savings

Validation

Use the Validator Tool to check your TOON syntax for errors.

Common errors:

  • Mismatched array length declarations
  • Inconsistent field counts in tabular arrays
  • Missing indentation for nested objects
  • Unquoted special characters in strings