TOON: El formato que reduce tus tokens y mejora tus LLMs

TOON (Token-Oriented Object Notation) es un formato de codificación compacto y legible para humanos, diseñado específicamente para enviar datos estructurados a modelos de lenguaje grande (LLMs) con hasta un 40% menos de tokens que JSON estándar.

Una capa de traducción entre tu código y los LLMs

TOON (Token-Oriented Object Notation) es un formato de codificación compacto y legible, diseñado específicamente para enviar datos estructurados a modelos de lenguaje grande. Es la respuesta a un problema concreto: JSON es verboso, y la verbosidad cuesta tokens. Los tokens cuestan dinero.

Piensa en TOON como un traductor: sigues usando JSON en tu código como siempre, pero cuando necesitas pasarle datos a un LLM, los conviertes a TOON para hacerlo de forma más eficiente. El modelo lee la estructura igual de bien — o mejor — y tú pagas hasta un 40% menos.

"Usa JSON programáticamente, codifícalo como TOON para los LLMs." — Documentación oficial de TOON

El mismo dato. Menos tokens.

Para ver la diferencia en la práctica, considera este dataset de excursiones:

En JSON (235 tokens):

{
  "context": {
    "task": "Our favorite hikes together",
    "location": "Boulder",
    "season": "spring_2025"
  },
  "friends": ["ana", "luis", "sam"],
  "hikes": [
    {
      "id": 1, "name": "Blue Lake Trail",
      "distanceKm": 7.5, "elevationGain": 320,
      "companion": "ana", "wasSunny": true
    },
    {
      "id": 2, "name": "Ridge Overlook",
      "distanceKm": 9.2, "elevationGain": 540,
      "companion": "luis", "wasSunny": false
    },
    {
      "id": 3, "name": "Wildflower Loop",
      "distanceKm": 5.1, "elevationGain": 180,
      "companion": "sam", "wasSunny": true
    }
  ]
}

En TOON (106 tokens — 55% menos):

context:
  task: Our favorite hikes together
  location: Boulder
  season: spring_2025
friends[3]: ana,luis,sam
hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:
  1,Blue Lake Trail,7.5,320,ana,true
  2,Ridge Overlook,9.2,540,luis,false
  3,Wildflower Loop,5.1,180,sam,true

El truco está en que TOON declara los campos una sola vez y transmite los valores como filas. Con datasets de decenas o cientos de registros, el ahorro es enorme.

Características principales

Eficiente en tokens. Declara los campos una sola vez y transmite los valores como filas. Compacidad similar a CSV pero con estructura explícita.

Round-trip lossless. decode(encode(x)) siempre es igual a x. Cero pérdida de datos. Listo para producción.

Guardarraíles para LLMs. Los [N] de longitud y los {campos} explícitos ayudan al modelo a seguir el esquema y detectar truncaciones.

Multi-lenguaje. Implementaciones estables en TypeScript, Python, Rust, Java, Swift y Julia. Comunidad activa en Go, C#, PHP, Ruby y más.

Tres estilos. Un formato.

TOON elige automáticamente el estilo más compacto según el tipo de dato:

Tipo de dato	Estilo	Ejemplo
Objeto anidado	Indentación YAML	`context:\n key: value`
Arreglo de primitivos	Inline	`friends[3]: a,b,c`
Arreglo uniforme de objetos	Tabla CSV	`items[2]{id,name}:\n 1,Alice\n 2,Bob`

La sintaxis completa en acción:

# Objeto anidado → indentación tipo YAML
context:
  task: Our favorite hikes
  location: Boulder

# Arreglo de primitivos → inline
friends[3]: ana,luis,sam

# Arreglo uniforme de objetos → tabla tipo CSV
hikes[3]{id,name,distanceKm,wasSunny}:
  1,Blue Lake Trail,7.5,true
  2,Ridge Overlook,9.2,false
  3,Wildflower Loop,5.1,true

Para usar TOON desde TypeScript:

import { encode, decode } from '@toon-format/toon'

// JSON → TOON (para el prompt)
const toon = encode(data)

// TOON → JSON (de vuelta a tu app)
const original = decode(toon, { strict: true })

Instalación: npm install @toon-format/toon

También disponible en Python, Rust, Java, Go, Swift, PHP, Ruby y más.

Ecosistema

TOON cuenta con implementaciones oficiales en TypeScript, Python, Rust, Java, Swift y Julia (todas en estado stable), y ports de la comunidad en Go, .NET y Dart (en desarrollo activo).

Además hay soporte comunitario para PHP, Ruby, Kotlin, C#, Elixir, Clojure, Scala, R y más.

Caso de uso 1: Filtrado de logs con Claude

Tienes logs de eventos y quieres pedirle a Claude que filtre solo los errores. Este flujo de 4 pasos muestra exactamente cómo funciona TOON en un pipeline real.

Paso 1 — Los logs llegan como JSON:

[
  { "id": 1, "level": "error", "message": "Connection timeout", "ts": "10:00" },
  { "id": 2, "level": "warn",  "message": "Slow query",         "ts": "10:05" },
  { "id": 3, "level": "info",  "message": "User login",         "ts": "10:10" },
  { "id": 4, "level": "error", "message": "Database error",     "ts": "10:15" }
]

Paso 2 — Conviertes a TOON con una línea:

import { encode } from '@toon-format/toon'

const toon = encode({ events: logs })
// events[4]{id,level,message,ts}:
//   1,error,Connection timeout,10:00
//   2,warn,Slow query,10:05
//   3,info,User login,10:10
//   4,error,Database error,10:15

Paso 3 — Envías el prompt a Claude:

System logs in TOON format:

```toon
events[4]{id,level,message,ts}:
  1,error,Connection timeout,10:00
  2,warn,Slow query,10:05
  3,info,User login,10:10
  4,error,Database error,10:15

Task: Return ONLY error-level events as TOON. Use the same format. Adjust [N] to match row count.


**Paso 4 — Validas la respuesta con strict mode:**

```typescript
import { decode } from '@toon-format/toon'

// Respuesta de Claude:
// events[2]{id,level,message,ts}:
//   1,error,Connection timeout,10:00
//   4,error,Database error,10:15

const result = decode(modelResponse, { strict: true })
// ✓ Validado: [N]=2, conteo de campos correcto
console.log(result.events) // [{id:1,...}, {id:4,...}]

Caso de uso 2: Pipeline de análisis con Claude Code

Conectas tu base de datos, codificas los datos en TOON, envías a Claude para análisis y recibes el resultado estructurado de vuelta:

import { encode, decode } from '@toon-format/toon'
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

// 1. Tus datos vienen como JSON de la base de datos
const users = await fetchUsersFromDatabase()

// 2. Conviertes a TOON → mucho más compacto para el prompt
const toonData = encode({ users })

// 3. Prompt con el bloque TOON embebido
const prompt = `
Analiza el siguiente dataset de usuarios en formato TOON:

\`\`\`toon
${toonData}
\`\`\`

Identifica usuarios sin login en los últimos 30 días.
Devuelve el resultado como TOON con el mismo esquema.
`

// 4. Envías a Claude
const response = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: prompt }],
})

// 5. Decodificas y validas la respuesta
const toonBlock = extractToonBlock(response.content[0].text)
const result = decode(toonBlock, { strict: true })

console.log('Usuarios para re-engagement:', result.users)

Tip: Claude Code tiene visibilidad de todo tu proyecto. Puedes pedirle directamente: "Encuentra todos los scripts que envían JSON a la API de Anthropic y optimízalos para usar TOON con @toon-format/toon." Claude Code instalará la dependencia, reemplazará la serialización y añadirá validación con modo estricto — sin que tengas que tocar cada archivo manualmente.

¿Cuándo usar TOON?

Úsalo cuando…

Tienes arreglos uniformes de objetos (misma estructura en cada fila)
Tus prompts incluyen datasets de decenas a miles de registros
El costo por token importa en pipelines frecuentes
Quieres que el modelo genere datos estructurados de vuelta
Trabajas con APIs que tienen rate limits o budgets de tokens ajustados

Evítalo cuando…

Las estructuras son profundamente anidadas y no uniformes (mejor JSON compacto)
El pipeline ya está establecido y el ROI no justifica el cambio
Los datos son puramente planos (CSV directo es más compacto aún)
La latencia es crítica (mide primero en tu entorno)
Tu equipo no está familiarizado y no hay tiempo para onboarding

Pruébalo hoy

La forma más rápida de experimentar es el Playground online: pega tu JSON y ve la conversión a TOON en tiempo real con el conteo de tokens comparado.

npm install @toon-format/toon