¿Qué es el formato TOON? Introducción para desarrolladores

La mayoría de los desarrolladores tienen una breve lista mental de formatos de datos: JSON para APIs, CSV para hojas de cálculo, YAML para archivos de configuración, quizás XML si trabajas con sistemas heredados. Pero hay un formato más nuevo que se está abriendo paso silenciosamente en el espacio de herramientas de IA y vale la pena conocer — TOON, o Token-Oriented Object Notation. Fue diseñado desde cero para resolver un problema específico: pasar datos estructurados a grandes modelos de lenguaje sin agotar tu presupuesto de tokens.

¿Qué es TOON?

TOON significa Token-Oriented Object Notation. Es un formato de serialización de datos compacto creado específicamente para minimizar el número de tokens consumidos cuando se incrustan datos estructurados en prompts LLM o respuestas. Piénsalo como JSON con toda la verbosidad eliminada — sin nombres de claves repetidos en arrays, sin comillas redundantes, sin espacios en blanco al final — solo la señal con el mínimo ruido sintáctico posible.

El paquete npm es @toon-format/toon, y te ofrece una API sencilla de encode / decode que funciona en cualquier proyecto Node.js o bundler moderno. Los archivos TOON usan la extensión .toon.

¿Por qué no simplemente usar JSON?

JSON es excelente para la comunicación máquina a máquina donde el ancho de banda es barato y el análisis es manejado por el runtime. Pero cuando envías datos como parte de un prompt a la API de OpenAI o la API de Anthropic, cada carácter cuenta — literalmente. Ambas APIs cobran por token, y los tokens corresponden aproximadamente a 4 caracteres de texto en inglés.

Considera una tabla de 100 registros de usuario. En JSON, repetirías las claves — "id", "name", "role", "email" — una vez por registro. Eso son 100 copias de la misma información estructural. La sintaxis tabular de TOON define esas claves una sola vez y luego lista los valores fila por fila, de la misma manera que lo hace un CSV, pero con la estructura de objeto preservada. El ahorro de tokens en conjuntos de datos del mundo real puede ser del 40-70% comparado con JSON compacto.

Sintaxis TOON de un vistazo

TOON soporta cuatro formas de datos principales: escalares (cadenas, números, booleanos), arrays, objetos y datos tabulares. La sintaxis escalar y de colección será familiar si has trabajado con JSON — el formato tabular es donde TOON realmente se diferencia.

Un objeto simple elimina el espacio en blanco de las llaves externas, omite comillas innecesarias y separa pares clave-valor con comas:

{name:Alice,age:30,role:admin}

Un array simple de escalares se ve exactamente como esperarías:

[1,2,3]

Ahora aquí es donde se pone interesante — los datos tabulares. Esta es la sintaxis que hace que TOON sea convincente para casos de uso de LLM. En lugar de repetir claves para cada objeto en un array, declaras el esquema una vez en el encabezado y listas los valores fila por fila:

users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Ese bloque representa un array de 3 objetos de usuario — equivalente al JSON a continuación — pero en una fracción de los tokens. El encabezado users[3]{id,name,role} le indica a un analizador: "esta es una variable llamada users, tiene 3 filas, y cada fila se corresponde con los campos id, name y role". Las filas son valores puros, sin repetición de claves.

[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

Instalación y uso del paquete @toon-format/toon

El paquete npm oficial maneja tanto la codificación de valores JavaScript a cadenas TOON como la decodificación de cadenas TOON de vuelta a objetos y arrays de JavaScript. Instálalo desde el registro npm:

npm install @toon-format/toon

El paquete exporta dos funciones — encode y decode:

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

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

La opción indent en encode() controla si la salida se formatea. Para prompts LLM, generalmente querrás una salida compacta (sin sangría) para ahorrar tokens. Para depuración o archivos .toon legibles por humanos, { indent: 2 } te da una salida bien formateada.

Un caso de uso real: enviar registros a un LLM

Imagina que estás construyendo una función de análisis de producto que necesita resumir la actividad del usuario. Obtienes registros de sesión recientes de tu base de datos y quieres enviarlos a un LLM para un resumen en lenguaje natural. Así es como se ve eso con TOON:

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

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

La representación TOON de esos 5 registros de sesión es significativamente más corta que el JSON equivalente, que repetiría "userId", "action", "duration" y "page" cinco veces cada uno. En cientos de registros el ahorro es sustancial, y se traduce directamente en costos de API más bajos y tiempos de respuesta más rápidos (menos tokens para procesar en la ventana de atención).

Tipos de datos clave en TOON

TOON se mapea limpiamente a los primitivos que ya usas en JavaScript y en la mayoría de los otros lenguajes:

• Cadenas — Sin comillas cuando no contienen caracteres especiales. Entre comillas dobles cuando incluyen comas, dos puntos o espacios en blanco.
• Números — Enteros y flotantes escritos tal cual: 42, 3.14, -7.
• Booleanos — true y false, igual que en JSON.
• Null — Escrito como null para valores ausentes o indefinidos.
• Arrays — Sintaxis de corchetes en línea [val1,val2,val3] para listas cortas; sintaxis de encabezado tabular para arrays de objetos.
• Objetos — Sintaxis de llaves {key:value,key2:value2} para objetos individuales.
• Datos tabulares — La estrella del espectáculo: encabezado name[n]{col1,col2,...}: seguido de filas separadas por comas — ideal para cualquier colección de registros con la misma forma.

Cuándo usar TOON vs otros formatos

TOON no intenta reemplazar JSON como formato de intercambio de propósito general. Ocupa un nicho específico. Aquí hay una guía de decisión rápida:

• Usa JSON cuando estés construyendo APIs REST, almacenando documentos en una base de datos o pasando datos entre servicios. JSON es universalmente compatible, bien soportado por herramientas y legible por humanos.
• Usa TOON cuando los datos estructurados son parte de un prompt o ventana de contexto LLM y el recuento de tokens importa. El formato tabular brilla cuando trabajas con filas de registros — listas de usuarios, entradas de registro, catálogos de productos, eventos analíticos.
• Usa CSV cuando solo necesitas datos tabulares planos y el consumidor espera CSV (hojas de cálculo, herramientas BI). CSV no tiene anidación de objetos, por lo que TOON es más expresivo.
• Usa YAML para archivos de configuración editados por humanos donde la legibilidad y los comentarios importan más que la compacidad.
• Usa TOON para salidas de herramientas LLM también: si un LLM llama a tu herramienta y devuelve resultados estructurados, codificar esos resultados en TOON ahorra tokens tanto en el lado de entrada como en el de salida de la llamada API.

Resumen

TOON — Token-Oriented Object Notation — es un formato de serialización compacto construido para la era LLM. Mantiene la estructura familiar de JSON (objetos, arrays, escalares) mientras introduce una sintaxis tabular que elimina la repetición redundante de claves entre registros. El resultado es un formato que puede ser un 40-70% más pequeño que el JSON equivalente, lo que se traduce directamente en menores costos de tokens al trabajar con la API de OpenAI, la API de Anthropic, o cualquier otro servicio LLM cobrado por token.

Si quieres explorar TOON de forma práctica, tenemos una suite completa de herramientas aquí: usa el formateador TOON para imprimir y examinar documentos TOON, el validador TOON para detectar errores de sintaxis, el convertidor JSON a TOON para migrar cargas útiles existentes, y el convertidor TOON a JSON si necesitas ir en la otra dirección. El paquete npm @toon-format/toon te da encode y decode para integrar TOON directamente en tu código Node.js o del lado del navegador en minutos.