Guía de sintaxis TOON — De escalares a datos tabulares

La mayoría de los formatos de datos fueron diseñados para una audiencia: humanos o máquinas. JSON se inclina hacia los humanos. Los formatos binarios como MessagePack se inclinan hacia las máquinas. TOON está diseñado explícitamente para una tercera audiencia que no existía cuando se inventaron esos formatos: los grandes modelos de lenguaje. Cada decisión sintáctica en TOON prioriza la eficiencia de tokens — caber el máximo de datos estructurados en el mínimo de tokens para poder pasar más contexto a una IA sin reventar tu presupuesto. Esta guía cubre cada característica de sintaxis TOON, desde scalares simples hasta la notación tabular que lo hace genuinamente diferente.

Lo que hace diferente a TOON

TOON significa Token-Optimised Object Notation. La idea central es simple: los formatos de serialización de datos como JSON fueron diseñados mucho antes de que la tarificación API por token fuera una realidad. JSON está bien para la comunicación máquina a máquina, pero cuando tu carga útil es un dataset de 200 filas que va a un prompt gpt-4o, estás pagando por cada comilla, cada llave y cada nombre de clave repetido. TOON elimina ese desperdicio. Se instala como un único paquete npm — @toon-format/toon — y los archivos usan la extensión .toon.

Valores escalares — cadenas, números, booleanos

Los escalares TOON se parecen mucho a sus homólogos JSON, con una diferencia importante: los valores de cadena no requieren comillas a menos que contengan caracteres especiales como comas, dos puntos o corchetes. Esto solo recorta una porción significativa de tokens en datasets pesados en texto.

// Numbers — exactly like JSON
42
3.14
-7

// Booleans — lowercase, same as JSON
true
false

// Strings — no quotes needed for simple values
hello
Alice
Widget Pro

Cuando una cadena contiene una coma, dos puntos o corchete, envuélvela en comillas dobles como en JSON. Así que "New York, NY" necesita comillas, pero London no. Regla simple, grandes ahorros.

Objetos — pares clave:valor sin el ruido

Los objetos TOON usan llaves con sintaxis key:value. Las claves nunca van entre comillas — eso solo ahorra dos caracteres por clave comparado con JSON. Los pares están separados por comas. Sin comas finales, sin dos puntos después del último par.

{name:Alice,age:31,city:London,active:true}

Compáralo con el JSON equivalente:

{"name": "Alice", "age": 31, "city": "London", "active": true}

Los mismos datos, menos caracteres, y el ahorro de tokens se multiplica dramáticamente cuando trabajas con arrays de objetos. Hablando de eso...

Arrays — listas ordenadas de valores

Los arrays en TOON usan corchetes con valores separados por comas — exactamente como JSON, solo sin comillas en valores de cadena simples.

// Array of strings
[Alice,Bob,Carol]

// Array of numbers
[10,20,30,40,50]

// Mixed types (same rules as JSON)
[Widget Pro,29.99,true,101]

// Array of objects
[{id:1,name:Alice},{id:2,name:Bob}]

Los arrays de objetos funcionan, pero aquí es donde entra la función estrella de TOON. Si tienes más de dos o tres filas de datos estructurados, la notación tabular es dramáticamente más eficiente.

Notación tabular — la función que cambia todo

La notación tabular es la función principal de TOON. Está diseñada para el escenario que encuentras constantemente en el trabajo real: una lista de objetos similares — productos, usuarios, transacciones, entradas de registro — donde repetir las claves en cada fila es puro desperdicio. La sintaxis es:

name[count]{col1,col2,col3,...}:
  row1val1,row1val2,row1val3
  row2val1,row2val2,row2val3

Desglosando: name es la etiqueta del dataset, [count] es el número de filas de datos (requerido — le dice al analizador exactamente cuántas líneas leer), {col1,col2,...} es la fila de encabezado, los dos puntos : terminan el encabezado, y cada línea indentada siguiente es una fila de valores. Aquí hay un ejemplo real de productos:

products[5]{id,name,price,inStock,category}:
  101,Widget Pro,29.99,true,Tools
  102,Gadget Plus,49.99,true,Electronics
  103,Thing Basic,9.99,false,Misc
  104,Super Doohickey,74.99,true,Electronics
  105,Budget Widget,14.99,true,Tools

Ahora imagina esos mismos datos como un array de objetos JSON. Escribirías "id", "name", "price", "inStock" y "category" cinco veces cada uno — más todas las llaves, corchetes y comillas circundantes. La representación TOON tabular es aproximadamente 60% más pequeña en recuento de tokens para esta forma de datos.

Un dataset de usuarios sigue el mismo patrón:

users[4]{id,username,email,role,active}:
  1,alice_dev,[email protected],admin,true
  2,bob_writer,[email protected],editor,true
  3,carol_ops,[email protected],viewer,false
  4,dan_qa,[email protected],editor,true

Anidamiento — objetos, arrays y tabular juntos

TOON admite anidamiento en los lugares que esperarías. Un objeto puede contener un valor de array. Una fila tabular puede contener un objeto. Esto te permite representar datos del mundo real que no encajan perfectamente en filas planas.

Objeto que contiene un array:

{name:Alice,roles:[admin,editor],active:true}

Datos tabulares con un objeto embebido en una columna (útil para datos de dirección, metadatos, etc.):

orders[3]{orderId,customer,total,address}:
  1001,alice_dev,89.97,{city:London,country:UK}
  1002,bob_writer,49.99,{city:Berlin,country:DE}
  1003,carol_ops,124.50,{city:Paris,country:FR}

Mantén el anidamiento poco profundo cuando sea posible. Dos o tres niveles de profundidad es donde TOON todavía gana en recuento de tokens. Las estructuras profundamente recursivas se sirven mejor con JSON, que tiene herramientas más ricas para la validación de esquema — ve la referencia JSON de MDN si necesitas eso.

Trabajar con el paquete npm

Instala con npm o cualquier gestor de paquetes compatible. TOON funciona en Node.js y navegadores modernos.

npm install @toon-format/toon

El paquete exporta dos funciones: encode y decode. Esa es toda la API pública — intencionalmente mínima.

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

// decode: TOON string → JS value
const toonString = `products[3]{id,name,price,inStock}:
  101,Widget Pro,29.99,true
  102,Gadget Plus,49.99,true
  103,Thing Basic,9.99,false`;

const data = decode(toonString);
console.log(data);
// [
//   { id: 101, name: "Widget Pro", price: 29.99, inStock: true },
//   { id: 102, name: "Gadget Plus", price: 49.99, inStock: true },
//   { id: 103, name: "Thing Basic", price: 9.99, inStock: false }
// ]

// encode: JS value → TOON string
const users = [
  { id: 1, username: 'alice_dev', active: true },
  { id: 2, username: 'bob_writer', active: false }
];

const toon = encode(users, { indent: 2 });
console.log(toon);
// users[2]{id,username,active}:
//   1,alice_dev,true
//   2,bob_writer,false

La opción { indent: 2 } controla la sangría de los valores de fila. También puedes usar encode en objetos simples y valores primitivos, no solo arrays — elige automáticamente la representación TOON más compacta. Pega la salida en el formateador TOON para inspeccionarla y mostrarla correctamente.

Errores comunes

Estos son los errores que afectan a los desarrolladores nuevos en TOON, generalmente dentro de la primera hora:

• Recuento de filas incorrecto en notación tabular. Escribir products[3] pero luego incluir 4 filas de datos causará un error de análisis o descartará silenciosamente la última fila dependiendo de la versión del analizador. Cuenta tus filas y mantén el número actualizado. El validador TOON lo detecta inmediatamente.
• Poner comillas en las claves de objeto. {"name":Alice} es TOON inválido — las claves nunca van entre comillas. Quita las comillas: {name:Alice}.
• Olvidar los dos puntos después del encabezado. products[2]{id,name} seguido de una nueva línea fallará. Necesitas los dos puntos finales: products[2]{id,name}:.
• Usar espacios alrededor de los dos puntos en pares clave:valor. {name : Alice} no es válido. Sin espacios: {name:Alice}.
• Incrustar comas en valores de cadena sin comillas. Si un nombre de producto es "Bolts, Nuts & More", debes entrecomillarlo en filas tabulares: 101,"Bolts, Nuts & More",4.99,true.
• Esperar salida JSON de decode en escalares. decode("42") devuelve el número JavaScript 42, no un objeto JSON. TOON decodifica a tipos JS nativos.

Convertir entre TOON y JSON

TOON y JSON son totalmente interconvertibles — TOON es un superconjunto del mismo modelo de datos lógico que JSON serializa. Usa JSON a TOON para reducir un dataset existente antes de enviarlo a un LLM, y TOON a JSON para volver a convertir cuando necesites alimentar el resultado en un sistema descendente solo JSON. Las funciones encode y decode manejan esto programáticamente si estás automatizando el flujo de trabajo en Node.js. La especificación de estructura de datos subyacente está estrechamente relacionada con conceptos del objeto global JSON en JavaScript.

Resumen

La sintaxis TOON es intencionalmente compacta. Sin claves entre comillas, sin nombres de claves repetidos en tablas, sin comillas obligatorias en valores de cadena simples. Una vez que hayas escrito un bloque tabular a mano, verás inmediatamente por qué — un dataset que toma 40 líneas de JSON cabe en 8 líneas de TOON. El paquete npm en npmjs.com/@toon-format/toon mantiene la superficie de la API diminuta: encode y decode, nada más que aprender. Usa el formateador TOON para mostrar correctamente, el validador TOON para detectar errores de sintaxis, JSON a TOON para convertir tus datos existentes, y TOON a JSON cuando necesites el resultado en forma estándar.