TOON Format (Token-Oriented Object Notation)

TOON is a compact, human-readable encoding of the JSON data model optimized for LLM prompts. It achieves ~40% token reduction compared to JSON while maintaining lossless round-trip compatibility.

Core Syntax Rules

Array Declaration

Arrays use bracketed headers with mandatory length count:

tags[3]: admin,ops,dev

Tabular Arrays (Uniform Object Arrays)

For arrays of objects with identical structure, use field headers in braces:

patterns[2]{id,category,summary}:
  P-001,pattern,"Use tokens for colors"
  P-002,mistake,"Check auth before routes"

• Field names declared once in {...} after the count
• Each row contains values in declared field order
• Rows indented with 2 spaces (NEVER tabs)

Objects

Objects use indentation-based nesting (2 spaces per level):

user:
  id: 123
  name: Ada

Quoting Rules (Critical)

Strings MUST be quoted if they contain:

• The active delimiter (comma by default)
• Empty string, leading/trailing whitespace
• Reserved literals (true, false, null)
• Numeric-like patterns
• Colons, quotes, backslashes, brackets, braces
• Control characters or leading hyphens

Escape sequences: \\, \", \n, \r, \t

org-patterns.toon Format

Standard format for ClosedLoop organization learnings:

patterns[N]{id,category,summary,confidence,seen_count,success_rate,flags,applies_to,context,repo}:
  P-001,pattern,"Summary here",high,5,0.85,,implementation-subagent,UI|styling,*
  P-002,mistake,"Check auth before routes",medium,3,0.60,[REVIEW],*,auth|routes,astoria-frontend

Field notes:

• summary - Always quoted (contains natural language with commas)
• flags - [REVIEW], [STALE], [UNTESTED], [PRUNE], or empty
• applies_to - Pipe-separated agent names or * for all
• context - Pipe-separated tags
• repo - Repository name (derived from git remote basename) or * for all repos

Validation Checklist

1. Count matches actual rows/items
2. Field count in rows matches declaration
3. Strings needing quotes are quoted
4. 2-space indentation (no tabs)
5. No blank lines within array blocks

References

• See references/examples.md for comprehensive examples
• TOON Specification
• Reference Implementation