TOON Best Practices: Mastering Naming, Nesting, and Error Handling

TOON is designed for deterministic structure and maximum token efficiency. However, like any precision tool, it yields the best results when used according to its core design principles. This post explores the technical best practices for naming and nesting, and provides a guide to troubleshooting common converter errors.

Best Practices: Naming & Structure

1. Naming Conventions (Key Encoding)

TOON is highly efficient with keys, but there are rules about when you can omit quotes. To keep your data readable and minimize token use, follow these naming guidelines:

• Unquoted Keys: Keys can be unquoted if they match the regex /^[A-Za-z_][A-Za-z0-9_.]*$/. This means they should start with a letter or underscore and contain only alphanumeric characters, underscores, or dots.
• Quoted Keys: If your key contains spaces, special characters (like -, :, or brackets), or starts with a number, it must be quoted and escaped.

2. Nesting: Indentation vs. Key Folding

While TOON supports standard indentation-based nesting (using 2 spaces), deep hierarchies can quickly become hard to read and parse.

The "Rule of Three": If your data goes deeper than three levels, consider using Key Folding. Key folding collapses nested objects into a single line using dot notation, which is often more token-efficient for LLMs.

user:
  profile:
    settings:
      theme: dark

user.profile.settings:
  theme: dark

3. When Not to use TOON

TOON is a specialized tool. You should not use it for:

• Highly Non-Uniform Data: If every object in an array has a completely different schema, JSON's repetitive keys are actually safer and clearer.
• Flat, non-nested tables: For simple spreadsheets without any nesting, CSV remains the king of raw density.
• Public Config Files: TOON is optimized for machine-to-machine (AI) communication. For user-facing config, YAML or TOML provide better comment support and flexibility.

Common Errors & Troubleshooting

The TOON reference implementation uses a "Strict Mode" by default to ensure data integrity. Here are the most common errors you'll encounter when converting malformed JSON or invalid TOON.

1. Array Count & Width Mismatches

This is the most common error. In TOON, array headers like items[3] or users[2]{id,name} are normative.

2. Indentation & Tab Errors

TOON is strict about whitespace:

• No Tabs: Tabs are forbidden for indentation. If a single tab character is found at the start of a line, the parser will error.
• Multiple of Indent Size: Indentation must be an exact multiple of the indentSize (default is 2 spaces).
• No Blank Lines in Arrays: You cannot have blank lines inside a tabular block or a list array. This ensures the structure is contiguous and predictable.

3. Syntax & Escaping

If you are getting Invalid escape sequence errors, check your quoted strings. TOON only supports a narrow set of escapes: \\n, \\r, \\t, \\", and \\\\. Any other backslash followed by a character will trigger a strict-mode error.