JSON Toolkit

Guía del formato TOON: aligerar el JSON antes de dárselo a un LLM

En resumen: Al pasar un array uniforme a un modelo de lenguaje en JSON, los nombres de clave repetidos y los corchetes consumen tokens. TOON declara la estructura una sola vez mediante objetos indentados y arrays tabulares, y despliega los datos línea por línea. Los benchmarks oficiales muestran cerca de un 40 % menos de tokens con mayor precisión de análisis. Esta guía cubre la sintaxis, cuándo aplican los ahorros, cuándo no conviene convertir y cómo conectar encode y decode.

Intermedio~6 min de lecturaPublicado el 2026-11-10Actualizado el 2026-11-10
Sintaxis del array tabular TOON: cabecera de campos declarada una vez, filas de datos desplegadas línea a línea

La sobrecarga sintáctica del JSON da igual en una transferencia entre máquinas, pero en el lado de entrada de un LLM facturado por tokens es dinero real: el mismo array uniforme repite sus nombres de clave decenas de veces, y cada llave y comilla se lleva una parte del presupuesto. TOON no inventa un nuevo modelo de datos: reescribe el modelo de datos JSON con una notación más barata.

Qué es TOON: otra codificación de JSON, no un competidor

TOON (Token-Oriented Object Notation) es un formato abierto aparecido en 2025, y su posicionamiento oficial cabe en una frase: una codificación compacta, sin pérdidas y legible del modelo de datos JSON. No introduce tipos nuevos — objetos, arrays, cadenas, números, booleanos y null se corresponden uno a uno con JSON, y decode(encode(x)) es estrictamente igual a los datos originales (los tipos fuera de JSON como Date o NaN deben normalizarse antes). El viaje de ida y vuelta es sin pérdidas y determinista: la misma entrada produce siempre la misma salida, algo importante para construir prompts reproducibles.

Como codifica exactamente el modelo de datos JSON, la forma correcta de usar TOON es como formato de frontera: la aplicación sigue trabajando en JSON internamente, convierte a TOON justo antes de meter los datos en un prompt y vuelve a convertir al recibir la respuesta del modelo. La documentación oficial lo llama "translation layer". La extensión de archivo convencional es .toon; para el transporte HTTP, el tipo de medio provisional es text/toon, en UTF-8.

Un aviso sobre ruido de búsqueda: no lo confundas con los Toon Shaders de los gráficos por computadora. Solo comparten la palabra.

Por qué el JSON es especialmente caro en la entrada de un LLM

Toma una lista de pedidos, un directorio de usuarios o un resumen de logs escritos como array JSON. Los tokens se van a tres sitios:

  1. Nombres de clave repetidos. Cincuenta registros de pedidos escriben "id", "amount" y "status" cincuenta veces cada uno. Dobla los datos y doblas la sobrecarga.
  2. Puntuación estructural. Llaves, corchetes, dos puntos y comas consumen todos tokens, y el anidado los empaqueta más densos.
  3. Comillas. Casi toda clave y valor de cadena va envuelto en comillas dobles.

El resultado: el coste de la API facturado por token sube directamente; las entradas largas tocan antes el techo de la ventana de contexto; y en entradas muy largas el modelo omite o desalinea campos con más frecuencia. El benchmark de la página oficial: sobre un conjunto de prueba de estructuras mixtas y cuatro modelos, cerca de un 40 % menos de tokens con la precisión de análisis subiendo del 70 % (JSON) al 74 % (TOON). Ahorro y precisión no se contraponen aquí, porque la estructura más compacta hace que los límites sean más visibles para el modelo.

La sintaxis: objetos indentados + arrays tabulares

Los mismos datos de previsión meteorológica en tres formas. Versión JSON, unos 117 tokens:

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

Versión TOON, unos 66 tokens:

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

Tres formas cubren todo, y el serializador las elige automáticamente según la forma de los datos:

Forma Encaja con Equivalente JSON
Objeto indentado Objetos anidados { "location": { ... } }, la indentación sustituye a las llaves
Array en línea Arrays de primitivos ["frost","wind"], [2] declara la longitud
Array tabular Arrays de objetos uniformes Los nombres de campo aparecen una sola vez en la cabecera {day,temp{min,max},...}; cada fila contiene solo valores separados por comas

Los objetos anidados uniformes (temp{min,max}) se pliegan en la cabecera como grupo de campos anidado, y las filas de datos quedan planas. La regla de comillas es mínima: las cadenas solo se entrecomillan si contienen delimitadores, caracteres especiales o podrían leerse como números — una de las razones por las que TOON supera al "JSON compacto" en recuento de tokens. La diferencia clave con YAML: TOON tiene declaraciones de longitud explícitas y cabeceras de campos que las máquinas pueden validar; con CSV: conserva el anidado y los tipos.

[N] y {fields}: barandillas estructurales para el modelo

[3] y {day,...} no son solo ahorro de tokens — son un contrato verificable entregado al modelo:

  • La longitud del array permite al modelo responder directamente "cuántos registros tiene el conjunto de datos" y revela al instante un truncamiento cuando el número de filas no cuadra.
  • La cabecera de campos declara los nombres una vez; el modelo alinea los valores por posición en vez de re-averiguar la correspondencia de claves en cada línea.

Esto es prevención, lo contrario del rescate posterior. Un reparador de JSON (ver la pipeline de reparación) recupera los datos después de que el modelo escupa JSON roto; las declaraciones de longitud y campos de TOON reducen en la entrada la probabilidad de datos rotos. Haz ambas cosas y la tasa de fallos de análisis en el medio del pipeline baja.

Cuándo no usar TOON

La sección oficial "When Not to Use TOON" es refrescantemente franca. Cuatro escenarios, que conviene copiar tal cual:

Escenario Por qué no Mejor opción
Estructuras profundamente anidadas, no uniformes Elegibilidad tabular ≈ 0 %; el JSON compacto suele ganar JSON compacto
Arrays semi-uniformes Campos desiguales, el ahorro se desvanece Mantener la pipeline JSON
Datos puramente tabulares TOON añade un 5–10 % de sobrecoste frente a CSV CSV
Sensible a latencia (modelos locales/cuantizados) Menos tokens ≠ inferencia más rápida Medir el TTFT primero

Lo semi-uniforme se juzga por la elegibilidad tabular (tabular eligibility): oficialmente, con un 40–60 % de elegibilidad el ahorro ya es marginal. Una migración de formato tiene coste real — parseadores, validadores y scripts aguas abajo cambian todos — así que si la ganancia es inferior al diez por ciento, no toques nada.

Puesta en marcha: encode / decode y la CLI

La biblioteca TypeScript oficial, en ambas direcciones:

npm install @toon-format/toon
# La conversión por lotes también pasa por la CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // estrictamente igual a los datos originales

Existen implementaciones en Python, Go, Rust y .NET; revisa la lista de implementaciones del repositorio oficial de la especificación antes de adoptar una, y confirma que cubre las características sintácticas que usas. Antes de producción, ejecuta una aserción de ida y vuelta: decode(encode(originales)) debe ser profundamente igual al original; si no, la implementación o los datos tienen un problema.

Cómo encaja en tu cadena JSON existente

TOON no cambia nada de tu pipeline JSON; añade una conversión de frontera. Orden recomendado:

  1. Asegúrate primero de que el JSON está limpio. Un JSON roto produce un TOON roto. La validación sintáctica y la reparación están cubiertas en la Guía de reparación de JSON.
  2. Comprueba la forma de los datos. ¿Los objetos del array tienen todos sus campos? Normaliza primero, o concluye que la conversión no merece la pena.
  3. Convierte y hace muestreo. Tras convertir, compara una fila de datos con el JSON original para confirmar que la alineación de campos no se ha desviado.
  4. Estima el beneficio. Para listas uniformes, el razonamiento línea a línea del manual de JSONL aplica a la conversión en flujo; para la relación entre tamaño y coste, la verdadera relación entre JSON minify y gzip da la misma lección: medir primero, convertir después.

¿TOON reemplazará a JSON?

No. TOON codifica el modelo de datos JSON; su lugar es la frontera del prompt, mientras que el almacenamiento y el intercambio entre programas siguen siendo territorio JSON. Usa TOON para el segmento "darle al modelo" y deja el resto de la cadena intacta.

¿Qué relación tiene TOON con YAML y CSV?

Los objetos se parecen a YAML (indentación en lugar de llaves); los arrays uniformes se parecen a CSV (cabecera declarada una vez, filas en flujo). Pero TOON tiene declaraciones de longitud explícitas que YAML carece, y conserva el anidado y los tipos que CSV carece — se queda entre los dos, con barandillas verificables por máquina.

¿La conversión de TOON a JSON pierde datos?

No: objetos, arrays, cadenas, números, booleanos y null se corresponden uno a uno, y decode(encode(x)) es estrictamente igual. La única precaución es normalizar antes los tipos fuera de JSON como Date y NaN; de lo contrario, la igualdad solo se cumple tras el viaje de ida y vuelta.

¿Cómo verifico que el TOON convertido es correcto?

Dos comprobaciones: una aserción de ida y vuelta (encode y luego decode, igualdad profunda con el original) y una inspección visual de la cabecera — el número de [N] debe igualar el número de filas, y los campos de {fields} deben alinearse uno a uno con los valores separados por comas de cada fila. Del lado del modelo, también puedes pedirle que informe de la longitud del array antes de responder.