TOON Best Practices

Write clean, efficient, and structured TOON for LLMs and agents.

Why Best Practices Matter

TOON is designed for clarity and token efficiency. Following these guidelines ensures that language models can parse your data reliably, reducing errors and saving costs.

Reduce Tokens

Fewer structural characters (`:`, `[]`, ``) means more of your context window is used for meaningful data.

Improve Reliability

A consistent, clean structure helps LLMs understand your data without ambiguity.

Enhance Readability

Well-formatted TOON is easier for developers to read, debug, and maintain.

Keep Keys Short and Meaningful

Concise keys reduce token count, but they should still be descriptive enough to be understood. Avoid overly verbose keys or cryptic abbreviations.

Anti-Pattern

user_information:
  user_identifier: 123
  full_user_name: "John Doe"
  user_email_address: "john.doe@example.com"

Good Practice

user:
  id: 123
  name: John Doe
  email: john.doe@example.com

Prefer Hierarchical Nesting

Nesting is TOON's strength. Use it to group related data logically, which improves readability and maps naturally to code objects.

post:
  id: 456
  title: My First Post
  author:
    id: 123
    name: John Doe
    handle: @johndoe

Use Arrays Correctly

TOON has specific formats for arrays of primitive values and arrays of objects. Using them correctly is key to efficient parsing.

Primitive Arrays

For lists of simple values like strings or numbers. Use a single line with comma-separated values.

tags[4]: "sci-fi", "dystopian", "classic", "must-read"

Tabular (Object) Arrays

For lists of objects with a consistent structure. Define columns in the header and provide data as CSV-style rows.

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

Avoid Deep Nesting

While powerful, nesting more than 3-4 levels deep can make data hard to read and process. If your structure gets too complex, consider flattening it.

Anti-Pattern

report:
  metadata:
    source:
      system:
        details:
          id: "sys-123"

Good Practice

report:
  id: "rpt-abc"
  source_system_id: "sys-123"

Use Schemas for Validation

For mission-critical applications, a schema ensures data integrity. Our Schema Builder tool can help you define and export a TOON-based schema.

Example Schema

A simple schema helps validate user data structures.

(schema User
    (id (type number) (description "Unique identifier"))
    (name (type string))
    (email (type string))
)

Anti-Patterns to Avoid

Avoid these common mistakes that can lead to parsing errors or inefficient token usage.

Anti-Pattern

# Repeating object keys inside a table
users[2]:
  user:
    id: 1
    name: Alice
  user:
    id: 2
    name: Bob

Good Practice

# Use a proper tabular array
users[2]{id,name}:
  1,Alice
  2,Bob

Anti-Pattern

# Using JSON-style quotes everywhere
"name": "Josh"
"age": 23

Good Practice

# Write strings as plain text
name: Josh
age: 23

Anti-Pattern

# Multi-line primitive arrays
friends[3]:
  ana
  luis
  sam

Good Practice

# Primitives should be on one line
friends[3]: ana, luis, sam

Final Checklist

A quick-reference list for writing perfect TOON.

  • Use 2-space indentation.
  • Keep keys short but meaningful.
  • Ensure `[N]` in array headers matches the row count.
  • Avoid nesting more than 4 levels deep.
  • Use tabular arrays for lists of objects.
  • Use single-line, comma-separated lists for primitive arrays.
  • Quote strings only if they contain spaces or special characters.