toon-formatter

Automatically apply TOON when:

• Arrays with 5+ similar objects
• API responses with repeated structure
• Database query results
• Log entries, events, transactions
• Metrics, analytics, benchmarks
• Any tabular data

Keep as JSON when:

• Small arrays (<5 items)
• Deeply nested non-uniform data
• Single objects
• Narrative text or instructions

Tabular Format (Most Common)

For arrays of uniform objects:

```

[count]{field1,field2,field3}:

value1,value2,value3

value1,value2,value3

```

Example - JSON (120 tokens):

```json

[

{"id": 1, "name": "Alice", "role": "admin", "active": true},

{"id": 2, "name": "Bob", "role": "user", "active": true},

{"id": 3, "name": "Carol", "role": "user", "active": false}

]

```

TOON (70 tokens, 42% savings):

```

[3]{id,name,role,active}:

1,Alice,admin,true

2,Bob,user,true

3,Carol,user,false

```

Inline Format

For primitive arrays (10 or fewer items):

```

fieldName[count]: value1,value2,value3

```

Example:

```

tags[4]: javascript,react,nodejs,api

ids[3]: 101,102,103

```

Expanded Format

For complex nested values (one per line):

```

items[3]|:

| {"complex": "object1"}

| {"complex": "object2"}

| {"complex": "object3"}

```

Delimiters

Choose based on data content:

| Delimiter | Syntax | Use When |

|-----------|--------|----------|

| Comma | [N] | Default, no commas in values |

| Tab | [N\t] | Values contain commas |

| Pipe | [N\|] | Values contain commas and tabs |

Tab-delimited example:

```

[2\t]{name,description}:

Product A A great product, really

Product B Another one, even better

```

Key Folding (Nested Objects)

Flatten nested structures:

```

server.host: localhost

server.port: 8080

server.ssl.enabled: true

database.url: postgres://localhost/db

```

Special Values

| Value | TOON Representation |

|-------|---------------------|

| null | ~ |

| empty string | "" |

| true | true |

| false | false |

API Response

Before (JSON):

```json

{

"users": [

{"id": 1, "email": "a@x.com", "plan": "pro"},

{"id": 2, "email": "b@x.com", "plan": "free"},

{"id": 3, "email": "c@x.com", "plan": "pro"}

],

"total": 3

}

```

After (TOON):

```

users[3]{id,email,plan}:

1,a@x.com,pro

2,b@x.com,free

3,c@x.com,pro

total: 3

```

Log Entries

Before (JSON):

```json

[

{"ts": "2024-01-15T10:00:00Z", "level": "INFO", "msg": "Server started"},

{"ts": "2024-01-15T10:00:01Z", "level": "DEBUG", "msg": "Connection pool ready"},

{"ts": "2024-01-15T10:00:02Z", "level": "INFO", "msg": "Listening on :8080"}

]

```

After (TOON):

```

[3]{ts,level,msg}:

2024-01-15T10:00:00Z,INFO,Server started

2024-01-15T10:00:01Z,DEBUG,Connection pool ready

2024-01-15T10:00:02Z,INFO,Listening on :8080

```

Database Results

Before (JSON):

```json

[

{"product_id": 101, "name": "Widget", "price": 29.99, "stock": 150},

{"product_id": 102, "name": "Gadget", "price": 49.99, "stock": 75},

{"product_id": 103, "name": "Gizmo", "price": 19.99, "stock": 200}

]

```

After (TOON):

```

[3]{product_id,name,price,stock}:

101,Widget,29.99,150

102,Gadget,49.99,75

103,Gizmo,19.99,200

```

Mixed Content

Combine formats as needed:

```

config.name: MyApp

config.version: 1.0.0

config.features[3]: auth,logging,metrics

endpoints[4]{method,path,auth}:

GET,/api/users,required

POST,/api/users,required

GET,/api/health,none

DELETE,/api/users/:id,admin

tags[5]: api,rest,json,http,web

```

```

Is it an array?

├─ No → Use standard JSON/key-value

└─ Yes → How many items?

├─ <5 → Keep as JSON (overhead not worth it)

└─ ≥5 → Are objects uniform (≥60% same keys)?

├─ No → Use expanded format

└─ Yes → Are values primitives?

├─ Yes, ≤10 items → Inline format

└─ Otherwise → Tabular format

```

| Data Type | Typical Savings |

|-----------|-----------------|

| User lists | 40-50% |

| Log entries | 35-45% |

| API responses | 30-50% |

| Database rows | 45-55% |

| Event streams | 40-60% |

| Config arrays | 25-35% |

A compiled Zig encoder (20x faster than JS) is available:

```bash

# Encode JSON to TOON

.claude/utils/toon/bin/toon encode data.json

# Decode TOON to JSON

.claude/utils/toon/bin/toon decode data.toon

# Check if TOON recommended

.claude/utils/toon/bin/toon check data.json

# Analyze token savings

.claude/utils/toon/bin/toon analyze data.json

```

| Command | Description |

|---------|-------------|

| /toon-encode | Convert JSON to TOON |

| /toon-decode | Convert TOON to JSON |

| /toon-validate | Validate TOON syntax |

| /analyze-tokens | Compare JSON vs TOON size |

| /convert-to-toon | Full conversion workflow |

DO:

• Use TOON for data payloads in RAG pipelines
• Apply to tool call responses with arrays
• Convert benchmark results and metrics
• Use tab delimiter when values have commas

DON'T:

• Convert small arrays (<5 items)
• Force non-uniform data into tabular format
• Use for deeply nested structures
• Apply to human-readable documentation

• Specification: https://github.com/toon-format/spec
• Website: https://toonformat.dev
• Local Guide: .claude/utils/toon/toon-guide.md