TOON Format Quick Reference

TL;DR: TOON format saves 23.6% tokens on average, reducing API costs by $169/month per 1000 daily calls.

Token Reduction Summary

┌─────────────────────────┬──────────────┬──────────────┬────────────┐
│ Response Type           │ JSON Tokens  │ TOON Tokens  │ Saved      │
├─────────────────────────┼──────────────┼──────────────┼────────────┤
│ Simple Error            │ 17           │ 12           │ 29.4%      │
│ User Profile            │ 80           │ 62           │ 22.5%      │
│ Todos List (3 items)    │ 272          │ 198          │ 27.2%      │
│ Large Nested Response   │ 428          │ 337          │ 21.3%      │
├─────────────────────────┼──────────────┼──────────────┼────────────┤
│ AVERAGE                 │ 797          │ 609          │ 23.6%      │
└─────────────────────────┴──────────────┴──────────────┴────────────┘

Cost Impact (GPT-4 Pricing)

Monthly Usage: 1,000 API calls/day × 30 days = 30,000 calls

┌─────────────┬────────────────┬──────────────┬────────────┐
│ Format      │ Tokens/Month   │ Cost/Month   │ Cost/Year  │
├─────────────┼────────────────┼──────────────┼────────────┤
│ JSON        │ 23.91M         │ $717.30      │ $8,607.60  │
│ TOON        │ 18.27M         │ $548.10      │ $6,577.20  │
├─────────────┼────────────────┼──────────────┼────────────┤
│ SAVINGS     │ 5.64M          │ $169.20      │ $2,030.40  │
└─────────────┴────────────────┴──────────────┴────────────┘

Side-by-Side Comparison

Simple Response

┌─────────────────────────────┬─────────────────────────────┐
│ JSON (17 tokens)            │ TOON (12 tokens)            │
├─────────────────────────────┼─────────────────────────────┤
│ {                           │ success: false              │
│   "success": false,         │ error: Not authorized       │
│   "error": "Not authorized",│ status: 401                 │
│   "status": 401             │                             │
│ }                           │                             │
└─────────────────────────────┴─────────────────────────────┘

Nested Object

┌─────────────────────────────┬─────────────────────────────┐
│ JSON (80 tokens)            │ TOON (62 tokens)            │
├─────────────────────────────┼─────────────────────────────┤
│ {                           │ id: user_123                │
│   "id": "user_123",         │ username: maker             │
│   "username": "maker",      │ first_name: John            │
│   "first_name": "John",     │ last_name: Doe              │
│   "last_name": "Doe",       │ avatar_url: ...             │
│   "avatar_url": "...",      │ url: ...                    │
│   "url": "...",             │ streaks: 42                 │
│   "streaks": 42,            │ completed_todos_count: 1337 │
│   "completed_todos_count":  │ best_streak: 89             │
│     1337,                   │ twitter_handle: johnmaker   │
│   "best_streak": 89,        │ created_at: ...             │
│   "twitter_handle":         │                             │
│     "johnmaker",            │                             │
│   "created_at": "..."       │                             │
│ }                           │                             │
└─────────────────────────────┴─────────────────────────────┘

Array of Objects

┌─────────────────────────────┬─────────────────────────────┐
│ JSON (272 tokens)           │ TOON (198 tokens)           │
├─────────────────────────────┼─────────────────────────────┤
│ {                           │ data:                       │
│   "data": [                 │   [0]                       │
│     {                       │     id: todo_1              │
│       "id": "todo_1",       │     body: Shipped new...    │
│       "body": "Shipped...", │     created_at: ...         │
│       "created_at": "...",  │     user:                   │
│       "user": {             │       id: user_123          │
│         "id": "user_123",   │       username: maker       │
│         "username": "maker" │     project:                │
│       },                    │       id: proj_1            │
│       "project": {          │       name: SaaS Product    │
│         "id": "proj_1",     │   [1]                       │
│         "name": "SaaS..."   │     id: todo_2              │
│       }                     │     body: Fixed bug...      │
│     },                      │     created_at: ...         │
│     {                       │     user:                   │
│       "id": "todo_2",       │       id: user_123          │
│       ...                   │       username: maker       │
│     }                       │     project:                │
│   ],                        │       id: proj_1            │
│   "has_more": false,        │       name: SaaS Product    │
│   "total_count": 2          │ has_more: false             │
│ }                           │ total_count: 2              │
└─────────────────────────────┴─────────────────────────────┘

Scaling Impact

┌────────────────┬────────────────┬────────────────┬────────────────┐
│ Daily Calls    │ JSON Cost/Mo   │ TOON Cost/Mo   │ Savings/Mo     │
├────────────────┼────────────────┼────────────────┼────────────────┤
│ 100            │ $71.73         │ $54.81         │ $16.92         │
│ 1,000          │ $717.30        │ $548.10        │ $169.20        │
│ 10,000         │ $7,173.00      │ $5,481.00      │ $1,692.00      │
│ 100,000        │ $71,730.00     │ $54,810.00     │ $16,920.00     │
└────────────────┴────────────────┴────────────────┴────────────────┘

Annual savings at 1,000 calls/day: $2,030.40

How to Enable

Already Enabled by Default! All OpenAPI pets use TOON format automatically.

To switch back to JSON:

{
  "openapiSpec": {
    "responseFormat": "json"
  }
}

Then regenerate:

pets generate-openapi

When to Use Each Format

Use Case	Recommended Format
LLM-powered app (Claude, GPT, etc.)	✅ TOON
High API call volume	✅ TOON
Cost optimization priority	✅ TOON
Browser/web client consumption	⚠️ JSON
Legacy system integration	⚠️ JSON
Binary data / complex types	⚠️ JSON

Performance Notes

• Conversion Overhead: <1ms for typical responses
• Network Size: ~10-15% larger than minified JSON
• LLM Processing: 23.6% fewer tokens
• Overall Impact: Net positive (token savings >> conversion cost)

Further Reading

• Full Documentation: toon-response.md
• TOON Spec: https://github.com/toon-format/toon
• OpenAPI Generator: openapi-generation.md

---

Last Updated: 2024-02-04 Tested With: WIP API, OpenSky API, and 4 diverse response types