Collection

---
name: moai-library-toon
aliases: [moai-library-toon]
category: library
description: TOON Format Specialist - Token-efficient data encoding for LLM communication optimized per TOON Spec v2.0
version: 3.0.0
modularized: true
tags:
  - library
  - architecture
  - toon
  - enterprise
  - patterns
updated: 2025-11-27
status: active
created: 2025-11-21
deprecated_names:
  moai-library-toon:
    deprecated_in: v0.32.0
    remove_in: v0.35.0
    message: "Use moai-library-toon instead"
---


## 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**
```python
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