Toon Format

1---2name: toon-format3description: Expert skill for Token-Oriented Object Notation (TOON) — compact, schema-aware JSON encoding for LLM prompts that reduces tokens by ~40%.4triggers:5  - convert JSON to TOON format6  - reduce LLM prompt tokens7  - encode data for LLM input8  - use TOON for AI prompts9  - serialize data with fewer tokens10  - TOON format encoding and decoding11  - token-efficient data format for language models12  - replace JSON with TOON in my prompt13---14 15# Token-Oriented Object Notation (TOON)16 17> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.18 19TOON is a compact, human-readable encoding of the JSON data model that minimizes tokens for LLM input. It combines YAML-style indentation for nested objects with CSV-style tabular layout for uniform arrays, achieving ~40% token reduction while maintaining or improving LLM comprehension accuracy.20 21## Installation22 23```bash24# npm25npm install @toon-format/toon26 27# pnpm28pnpm add @toon-format/toon29 30# yarn31yarn add @toon-format/toon32```33 34## CLI35 36```bash37# Install globally38npm install -g @toon-format/toon39 40# Convert JSON file to TOON41toon encode input.json42toon encode input.json -o output.toon43 44# Convert TOON back to JSON45toon decode input.toon46toon decode input.toon -o output.json47 48# Pipe support49cat data.json | toon encode50cat data.toon | toon decode51 52# Pretty-print JSON output53toon decode input.toon --pretty54 55# Show token count comparison56toon encode input.json --stats57```58 59## Core API60 61### encode / stringify62 63```typescript64import { encode, decode } from '@toon-format/toon';65 66// Basic encoding (JSON → TOON string)67const data = {68  context: {69    task: 'Our favorite hikes together',70    location: 'Boulder',71    season: 'spring_2025',72  },73  friends: ['ana', 'luis', 'sam'],74  hikes: [75    { id: 1, name: 'Blue Lake Trail', distanceKm: 7.5, elevationGain: 320, companion: 'ana', wasSunny: true },76    { id: 2, name: 'Ridge Overlook', distanceKm: 9.2, elevationGain: 540, companion: 'luis', wasSunny: false },77    { id: 3, name: 'Wildflower Loop', distanceKm: 5.1, elevationGain: 180, companion: 'sam', wasSunny: true },78  ],79};80 81const toon = encode(data);82console.log(toon);83// context:84//   task: Our favorite hikes together85//   location: Boulder86//   season: spring_202587// friends[3]: ana,luis,sam88// hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:89//   1,Blue Lake Trail,7.5,320,ana,true90//   2,Ridge Overlook,9.2,540,luis,false91//   3,Wildflower Loop,5.1,180,sam,true92```93 94### decode / parse95 96```typescript97import { decode } from '@toon-format/toon';98 99const toonString = `100context:101  task: Our favorite hikes together102  location: Boulder103friends[2]: ana,luis104hikes[2]{id,name,distanceKm}:105  1,Blue Lake Trail,7.5106  2,Ridge Overlook,9.2107`;108 109const parsed = decode(toonString);110// Returns the original JavaScript object111console.log(parsed.hikes[0].name); // 'Blue Lake Trail'112```113 114### Encoding options115 116```typescript117import { encode } from '@toon-format/toon';118 119const toon = encode(data, {120  // Force all arrays to tabular format (default: auto-detect uniform arrays)121  tabular: 'always',122 123  // Never use tabular format124  // tabular: 'never',125 126  // Indent size for nested objects (default: 2)127  indent: 2,128 129  // Quote strings that contain special characters (default: auto)130  quoting: 'auto',131});132```133 134## Format Overview135 136### Primitive scalars137 138TOON encodes scalars the same way as YAML — unquoted when unambiguous:139 140```141name: Alice142age: 30143active: true144score: 98.6145nothing: null146```147 148### Nested objects (YAML-style indentation)149 150```151user:152  name: Alice153  address:154    city: Boulder155    zip: 80301156```157 158### Flat arrays (scalar items)159 160Square brackets declare the array length, values are comma-separated:161 162```163tags[3]: typescript,llm,serialization164scores[4]: 10,20,30,40165```166 167### Uniform object arrays (tabular format)168 169Curly braces declare the field headers; each subsequent indented line is a row:170 171```172employees[3]{id,name,department,salary}:173  1,Alice,Engineering,95000174  2,Bob,Marketing,72000175  3,Carol,Engineering,102000176```177 178### Quoting rules179 180Values containing commas, colons, or newlines are quoted:181 182```183notes[2]: "hello, world","line1\nline2"184messages[1]{from,text}:185  alice,"See you at 3:00, okay?"186```187 188### Mixed nesting189 190```191company:192  name: Acme Corp193  founded: 1987194  offices[2]: NYC,SF195  teams[2]{name,headcount}:196    Engineering,45197    Marketing,20198```199 200## Using TOON with LLMs201 202### Direct prompt injection203 204```typescript205import { encode } from '@toon-format/toon';206import OpenAI from 'openai';207 208const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });209 210async function queryWithToon(data: unknown, question: string) {211  const toon = encode(data);212 213  const response = await client.chat.completions.create({214    model: 'gpt-4o-mini',215    messages: [216      {217        role: 'system',218        content: [219          'You are a data analyst. The user will provide data in TOON format.',220          'TOON is a compact encoding of JSON: indentation = nesting,',221          'key[N]: v1,v2 = array of N scalars,',222          'key[N]{f1,f2}: rows = array of N objects with fields f1, f2.',223        ].join(' '),224      },225      {226        role: 'user',227        content: `Data:\n\`\`\`\n${toon}\n\`\`\`\n\nQuestion: ${question}`,228      },229    ],230  });231 232  return response.choices[0].message.content;233}234 235// Usage236const employees = [237  { id: 1, name: 'Alice', dept: 'Eng', salary: 95000 },238  { id: 2, name: 'Bob', dept: 'Marketing', salary: 72000 },239];240 241const answer = await queryWithToon(242  { employees },243  'Who has the highest salary?'244);245```246 247### Anthropic / Claude248 249```typescript250import { encode } from '@toon-format/toon';251import Anthropic from '@anthropic-ai/sdk';252 253const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });254 255async function analyzeWithClaude(data: unknown, prompt: string) {256  const toon = encode(data);257 258  const message = await client.messages.create({259    model: 'claude-haiku-4-5-20251001',260    max_tokens: 1024,261    system:262      'Data is in TOON format: indented = nested objects, key[N]: vals = scalar array, key[N]{fields}: rows = object array.',263    messages: [264      {265        role: 'user',266        content: `\`\`\`toon\n${toon}\n\`\`\`\n\n${prompt}`,267      },268    ],269  });270 271  return message.content[0].type === 'text' ? message.content[0].text : null;272}273```274 275### Token count comparison utility276 277```typescript278import { encode } from '@toon-format/toon';279import { encode as gptEncode } from 'gpt-tokenizer';280 281function compareTokens(data: unknown) {282  const jsonStr = JSON.stringify(data);283  const toonStr = encode(data);284 285  const jsonTokens = gptEncode(jsonStr).length;286  const toonTokens = gptEncode(toonStr).length;287  const savings = (((jsonTokens - toonTokens) / jsonTokens) * 100).toFixed(1);288 289  console.log(`JSON:  ${jsonTokens} tokens`);290  console.log(`TOON:  ${toonTokens} tokens`);291  console.log(`Saved: ${savings}%`);292 293  return { jsonTokens, toonTokens, savings: parseFloat(savings) };294}295```296 297## Common Patterns298 299### Batch API calls with TOON300 301```typescript302import { encode } from '@toon-format/toon';303 304// Encode each record separately for independent LLM calls305function encodeRecords<T>(records: T[]): string[] {306  return records.map((r) => encode(r));307}308 309// Encode all records as one TOON document (most efficient for bulk)310function encodeAll<T>(records: T[], key = 'records'): string {311  return encode({ [key]: records });312}313```314 315### RAG / retrieval context injection316 317```typescript318import { encode } from '@toon-format/toon';319 320interface SearchResult {321  id: string;322  title: string;323  snippet: string;324  score: number;325  url: string;326}327 328function buildRagContext(results: SearchResult[]): string {329  // TOON is ideal here — uniform objects collapse into a compact table330  return encode({ results });331}332 333// Output:334// results[5]{id,title,snippet,score,url}:335//   doc1,Introduction to TOON,...,0.95,https://...336//   doc2,TOON vs JSON,...,0.87,https://...337```338 339### Streaming encode for large datasets340 341```typescript342import { encode } from '@toon-format/toon';343import { createReadStream, createWriteStream } from 'fs';344 345// For large JSON files: read → parse → encode → write346async function convertFile(inputPath: string, outputPath: string) {347  const raw = await fs.promises.readFile(inputPath, 'utf-8');348  const data = JSON.parse(raw);349  const toon = encode(data);350  await fs.promises.writeFile(outputPath, toon, 'utf-8');351 352  const jsonBytes = Buffer.byteLength(raw);353  const toonBytes = Buffer.byteLength(toon);354  console.log(`Reduced size by ${(((jsonBytes - toonBytes) / jsonBytes) * 100).toFixed(1)}%`);355}356```357 358### Schema-aware encoding (TypeScript)359 360```typescript361import { encode, decode } from '@toon-format/toon';362 363interface Employee {364  id: number;365  name: string;366  department: string;367  salary: number;368  active: boolean;369}370 371interface EmployeeReport {372  generatedAt: string;373  employees: Employee[];374}375 376// Encode is generic-friendly — pass any serializable object377const report: EmployeeReport = {378  generatedAt: new Date().toISOString(),379  employees: [380    { id: 1, name: 'Alice', department: 'Engineering', salary: 95000, active: true },381    { id: 2, name: 'Bob', department: 'Marketing', salary: 72000, active: true },382  ],383};384 385const toon = encode(report);386 387// Decode back with type assertion388const recovered = decode(toon) as EmployeeReport;389console.log(recovered.employees[0].name); // 'Alice'390```391 392### Express middleware for TOON content-type393 394```typescript395import express from 'express';396import { encode, decode } from '@toon-format/toon';397 398const app = express();399 400// Parse incoming TOON bodies401app.use((req, res, next) => {402  if (req.headers['content-type']?.startsWith('text/toon')) {403    let body = '';404    req.on('data', (chunk) => (body += chunk));405    req.on('end', () => {406      try {407        (req as any).toonBody = decode(body);408        next();409      } catch (e) {410        res.status(400).json({ error: 'Invalid TOON body' });411      }412    });413  } else {414    next();415  }416});417 418// Respond with TOON when client requests it419app.get('/api/employees', (req, res) => {420  const employees = [421    { id: 1, name: 'Alice', dept: 'Eng' },422    { id: 2, name: 'Bob', dept: 'Marketing' },423  ];424 425  if (req.headers.accept?.includes('text/toon')) {426    res.setHeader('Content-Type', 'text/toon; charset=utf-8');427    res.send(encode({ employees }));428  } else {429    res.json({ employees });430  }431});432```433 434## When to Use TOON vs JSON435 436| Scenario | Recommendation |437|---|---|438| Uniform arrays of objects | ✅ TOON (biggest savings) |439| Deeply nested / non-uniform | ⚠️ Benchmark both; JSON-compact may win |440| Pure flat tabular data | Consider CSV (smaller) or TOON (structured) |441| Latency-critical (local models) | Benchmark TTFT + tokens/sec |442| Programmatic API calls | Keep JSON; encode to TOON only for LLM input |443| Semi-uniform (~40–60% tabular) | Benchmark; savings diminish |444 445## Troubleshooting446 447### Values with commas parse incorrectly448 449Wrap them in double quotes in your TOON string, or ensure `encode()` handles it automatically:450 451```typescript452// encode() automatically quotes values containing commas453const data = { tags: ['hello, world', 'foo,bar'] };454encode(data);455// tags[2]: "hello, world","foo,bar"456```457 458### Round-trip type loss (numbers vs strings)459 460TOON uses unquoted values for numbers and booleans. Ensure your data uses proper JS types before encoding — don't pass `"95000"` (string) when you mean `95000` (number):461 462```typescript463// ✅ Correct464{ salary: 95000, active: true }465 466// ❌ Will decode as string "95000" and string "true"467{ salary: '95000', active: 'true' }468```469 470### LLM misreads tabular rows471 472Add a brief TOON format explanation to your system prompt:473 474```475TOON format rules:476- Indentation = nested object477- key[N]: v1,v2,v3 = array of N scalar values478- key[N]{field1,field2}: followed by N indented rows = array of objects479```480 481### CLI not found after global install482 483```bash484# Verify global bin path is on your PATH485npm bin -g   # or: npm root -g486 487# Alternatively use npx488npx @toon-format/toon encode input.json489```490 491### Decoding fails on hand-written TOON492 493Common mistakes in hand-written TOON:494- Missing length declaration: `items{id,name}:` → must be `items[2]{id,name}:`495- Inconsistent indentation (mix of tabs/spaces)496- Unquoted values containing `:` as first character497 498## Resources499 500- [Official Specification (SPEC v3.0)](https://github.com/toon-format/spec/blob/main/SPEC.md)501- [npm package: @toon-format/toon](https://www.npmjs.com/package/@toon-format/toon)502- [Online Playground](https://toonformat.dev)503- [GitHub Repository](https://github.com/toon-format/toon)