moai-library-toon

Quick Reference (30 seconds)

TOON (Token-Optimized Object Notation) is a token-efficient data encoding format designed for LLM communication. It reduces token consumption by 40-60% compared to JSON while maintaining readability and structure.

Key Benefits:

• 40-60% token reduction vs JSON
• Hierarchical structure with minimal delimiters
• Human-readable and LLM-parseable
• Optimized for Claude and GPT models

Use Cases:

• Large dataset transmission to LLMs
• API responses with token budget constraints
• Configuration files for AI agents
• Structured data in long-context scenarios

Implementation Guide (5 minutes)

Features

• Compact hierarchical notation (: for key-value, | for arrays)
• Minimal delimiters and whitespace
• Type inference without explicit markers
• Native support for nested structures
• 100% lossless encoding/decoding

When to Use

• Transmitting large datasets to LLMs within token limits
• Optimizing prompt engineering with structured data
• Reducing API costs in high-volume LLM applications
• Encoding configuration or state data for AI agents
• Improving context window utilization in long conversations

Core Patterns

Pattern 1: Basic TOON Encoding

# JSON (150 tokens)
{
  "user": {"name": "Alice", "age": 30},
  "items": ["apple", "banana"]
}

# TOON (80 tokens) - 47% reduction
user:name|Alice,age|30
items:apple|banana

Pattern 2: Complex Nested Structures

project:MoAI-ADK,version|0.28.0
agents:workflow-spec|workflow-tdd|code-backend
config:enforce_tdd|true,coverage|90

Pattern 3: TOON Encoding Function

def encode_toon(data: dict) -> str:
    lines = []
    for key, value in data.items():
        if isinstance(value, dict):
            items = [f"{k}|{v}" for k, v in value.items()]
            lines.append(f"{key}:{','.join(items)}")
        elif isinstance(value, list):
            lines.append(f"{key}:{'|'.join(map(str, value))}")
        else:
            lines.append(f"{key}:{value}")
    return '\n'.join(lines)

Advanced Implementation (10+ minutes)

TOON Spec 2.0 Features

Type Annotations:

# Optional type hints for clarity
user:name|Alice:str,age|30:int,active|true:bool

Compression Strategies:

• Short keys (u:user, c:config)
• Abbreviations (enf:enforce, cov:coverage)
• Omit null/empty values
• Collapse single-item arrays

Performance Metrics:

• 40-60% token reduction (typical)
• Up to 70% reduction (highly structured data)
• 100% accuracy (lossless encoding)
• <1ms encoding/decoding time

Reference Materials

• Core Implementation: modules/core.md
• Advanced Patterns: modules/advanced.md
• TOON Spec 2.0: Official specification document

Implementation Modules

For detailed patterns:

• Core Implementation: modules/core.md
• Advanced Patterns: modules/advanced.md

End of Skill | Updated 2025-11-21

Works Well With

Agents:

• code-frontend - UI implementation
• design-uiux - Design integration
• workflow-tdd - Testing integration

Skills:

• moai-library-shadcn - Complementary UI library
• moai-foundation-react - React integration
• moai-testing-frontend - Frontend testing

Commands:

• /moai:2-run - Testing with Toon UI
• /moai:3-sync - Component documentation