TOON Best Practices: 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. Since TOON v4 a dotted key such as metadata.created_at is just a literal key name. It is never expanded into nested objects.
• 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 and Nested Field Groups

TOON nests objects with indentation (2 spaces by default). Deep hierarchies cost indentation tokens on every line and get harder for models to follow, so keep the structure as shallow as your use case allows.

Key folding is gone. Older guides (including an earlier version of this post) recommended folding deep paths into dotted keys like user.profile.settings:. Key folding and path expansion were removed in spec 4.0, and @toon-format/toon 4.1.1 ignores the old keyFolding option. You have two options instead:

• Arrays of uniform nested objects: let the encoder use nested field groups. The nested fields move into the header, and rows stay flat.
• Deep, one-off config objects: flatten them in your application before encoding (for example, pick only the leaf values the model needs).

user:
  profile:
    settings:
      theme: dark

users[2]{id,profile{settings{theme}}}:
  1,dark
  2,light

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. The official README estimates TOON adds about 5-10% overhead over CSV in exchange for length and field headers.
• Public Config Files: TOON is optimized for machine-to-machine (AI) communication. It gained full-line # comments in v4 (no inline comments), but for user-facing config YAML or TOML still offer richer comment support and tooling. When that config has to go into a prompt, convert it with the YAML to TOON or TOML to TOON converter.

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). Error: Indentation must be exact multiple of 2, but found 3 spaces.
• No Depth Jumps: Since spec 4.0, a line indented more than one level deeper than its parent is a strict-mode error (Indentation depth jump: expected depth 1, but found 3).
• 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.

In JavaScript, all of these surface as a ToonDecodeError (exported by @toon-format/toon since 2.2.0) with the line number in the message, e.g. Line 3: Expected 2 tabular row values, but got 1.

4. "Why is my comment showing up as data?"

TOON comments are full-line only: a line whose first non-space character is # is ignored. A # anywhere else is ordinary content, so timeout: 5000 # ms decodes as the string "5000 # ms", not the number 5000. Put the comment on its own line. For the same reason, string values that start with # must be quoted, and the encoder does this for you.