TOON vs JSON vs CSV — Elegir el formato correcto

Tres formatos entran en una reunión de planificación. JSON dice que puede manejar todo. CSV dice que es rápido y ligero. TOON dice que está aquí para hablar con la IA. Todos tienen razón — para diferentes trabajos. La parte frustrante no es que estos formatos existan, es que elegir el incorrecto para tu caso de uso te cuesta de maneras reales y concretas: cargas útiles verbosas, importaciones rotas, facturas LLM costosas, o dolores de cabeza con el análisis. Esta guía te da un marco claro para elegir.

Un retrato rápido de cada formato

JSON (JavaScript Object Notation) surgió de JavaScript a principios de los 2000 y se convirtió en el formato dominante para las APIs web gracias a su simplicidad y expresividad. Maneja estructuras anidadas de forma nativa, distingue entre cadenas, números, booleanos y nulls sin ninguna ceremonia extra, y está especificado por RFC 8259. Todos los lenguajes modernos tienen una biblioteca JSON de primera clase.

CSV (Comma-Separated Values) es más antiguo que la web. Está definido por RFC 4180 y es esencialmente la lengua franca de los datos tabulares planos. Abre cualquier CSV en Excel, Google Sheets, o Numbers y simplemente funciona. Para tablas planas puras, es el formato más compacto y universalmente importable que existe.

TOON es un formato más reciente construido específicamente para flujos de trabajo LLM. Toma inspiración de ambos — como CSV usa una estructura de encabezado-una-vez-luego-filas para datos tabulares, pero como JSON también puede codificar objetos y arrays anidados. Todo su diseño está orientado hacia la minimización del recuento de tokens al pasar datos hacia y desde grandes modelos de lenguaje.

Los mismos datos en los tres formatos

Para hacer esto concreto, usemos un catálogo de productos que incluye un objeto specs anidado — una forma del mundo real que ejercita los tres formatos de manera significativa. Aquí hay cuatro productos de una tienda de electrónica:

JSON — expresivo, maneja el anidamiento naturalmente, pero verboso para datos de filas repetitivas:

[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — compacto, compatible con Excel, pero el objeto specs anidado tiene que ser aplanado. No hay forma estándar de representarlo, así que o perdemos el anidamiento o lo retorcemos en una cadena:

id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440

TOON — encabezado declarado una vez, filas compactas, objetos anidados codificados en línea:

products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

Dónde falla cada formato

Entender los modos de fallo es tan importante como conocer las fortalezas.

• JSON falla para tablas. Repetir cada nombre de clave en cada fila es genuinamente derrochador. Un dataset de 1000 filas donde cada fila tiene 8 claves significa que "id", "name", "price" y así sucesivamente se escriben 1000 veces cada uno. Para entrada LLM esto se traduce directamente en costo de tokens; para la inspección humana es solo ruido.
• CSV falla para datos anidados. El formato no tiene concepto de anidamiento. Puedes convertir un objeto anidado en una cadena en una celda, pero luego el consumidor tiene que saber analizar esa celda — solo has movido el problema. CSV tampoco tiene sistema de tipos nativo: true es una cadena, 42 es una cadena, null es ambiguo. Las herramientas manejan esto de manera inconsistente.
• TOON falla fuera de los contextos LLM. Es un formato de nicho con un ecosistema más estrecho. No encontrarás soporte TOON nativo en PostgreSQL, en tu framework REST, o en Excel. El paquete npm cubre bien los flujos de trabajo JavaScript/TypeScript, pero si estás usando TOON en un contexto que no tiene nada que ver con IA, probablemente estés sobre-ingeniando.
• CSV falla para valores que contienen comas o saltos de línea. Las reglas de comillas RFC 4180 lo manejan, pero muchos productores y consumidores CSV las implementan de manera inconsistente. Un nombre de producto como 27" IPS Monitor, Black o una descripción con saltos de línea se convierte en un riesgo de fiabilidad.

Matriz de decisión

Aquí hay una guía práctica. Asocia tu situación con el formato apropiado:

• Tus datos van a un prompt LLM → TOON. Especialmente si es tabular. Usa JSON a TOON para convertir antes de la llamada API.
• Tus datos vienen de un LLM y necesitan ser procesados → TOON (para salida), luego decodifica a JSON o un objeto nativo para uso descendente con TOON a JSON.
• Tus datos son puramente tabulares planos (mismas claves en cada fila) y van hacia/desde hojas de cálculo → CSV. Es la representación más pequeña y universalmente importable.
• Tus datos son tabulares planos pero serán transformados por código (no hojas de cálculo) → CSV o JSON. JSON es más seguro si los tipos importan (no quieres "true" en lugar de true).
• Tus datos tienen objetos o arrays anidados → JSON. No luches contra la limitación solo-plano de CSV. Si el anidamiento va a un LLM, codifica a TOON después de construir la estructura.
• Tus datos van a una API REST o se almacenan en una base de datos → JSON. Siempre.
• Tus datos son un archivo de configuración → JSON o YAML. Ni CSV ni TOON pertenece aquí.
• Necesitas máxima portabilidad y un analizador sin dependencias → JSON o CSV. Ambos tienen soporte nativo o casi nativo en todas partes.

Usar los tres en un mismo pipeline

Un pipeline realista podría usar los tres. Imagina un flujo de trabajo de comercio electrónico que enriquece datos de productos con descripciones generadas por IA:

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

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

JSON para la capa API, TOON a través de la capa LLM, CSV para la salida consumible por humanos. Cada formato está haciendo exactamente el trabajo para el que fue diseñado.

Referencia rápida de herramientas

Si te mueves entre estos formatos, estas herramientas cubrirán las conversiones comunes. El formateador TOON es la forma más rápida de validar y limpiar cadenas TOON. El convertidor JSON a TOON maneja el paso de preparación LLM. Yendo en la otra dirección después de que un LLM devuelva TOON, TOON a CSV puede producir una exportación lista para hoja de cálculo directamente, y CSV a JSON es el estándar para normalizar importaciones desde Excel o proveedores de datos de terceros. Para detalles específicos de TOON, el paquete oficial vive en npm.

Resumen

JSON, CSV y TOON tienen cada uno un dominio claro. JSON es el formato universal para el intercambio de datos estructurados — anidado o plano, APIs, configuración, almacenamiento. CSV es el formato universal para datos tabulares planos que necesitan viajar entre sistemas y humanos — hojas de cálculo, importaciones, exportaciones. TOON es el formato para pasar datos estructurados a través de sistemas de IA de manera eficiente, donde cada token cuenta. El error que cometen la mayoría de los desarrolladores es recurrir por defecto a JSON para todo incluyendo los prompts LLM, o recurrir por defecto a CSV y luego descubrir los requisitos de anidamiento a mitad del proyecto. Conoce la forma de tus datos, sabe a dónde van, y el formato correcto generalmente se elige solo.

Para un análisis más profundo del compromiso JSON vs TOON específicamente, consulta la comparación TOON vs JSON. Para información sobre la especificación CSV y sus peculiaridades, el artículo de Wikipedia sobre CSV cubre bien la historia y las variaciones de formato.