YAML y TOON se describen ambos como "más legibles que JSON" — y esa descripción es técnicamente verdadera para ambos, lo que la hace inútil. La pregunta real es: legible para quién, ¿y con qué propósito? YAML está optimizado para la edición humana: comentarios, anclas, cadenas multilínea, sangría que refleja cómo los desarrolladores piensan sobre la configuración. TOON está optimizado para el procesamiento de máquinas: tokens mínimos, sin ambigüedad, sin sintaxis que exista puramente para el confort humano. Estos son trabajos diferentes. Confundirlos lleva a YAML en prompts de LLM — lo cual es peor que JSON — y TOON en manifests de Kubernetes, que nadie quiere editar a mano. Este artículo traza la línea claramente.

YAML en Dos Oraciones

YAML es un formato de serialización de datos amigable para humanos diseñado para archivos de configuración, pipelines CI/CD, y cualquier documento estructurado que un desarrollador leerá, escribirá y mantendrá a mano. Sus características definitorias — comentarios inline, mecánicas DRY de ancla/alias, literales de cadena multilínea, y estructura basada en sangría — todas existen para hacer el formato agradable para humanos, no eficiente para máquinas.

Los casos de uso canónicos son los workflows de GitHub Actions, los manifests de Kubernetes, los archivos Docker Compose, y la configuración de aplicaciones que se envía junto con el código. Si se espera que un ser humano abra el archivo y lo edite, YAML es una elección sólida. La especificación YAML 1.2 formalizó varios casos extremos que plagaron YAML 1.1 — el más famoso fue el Problema de Noruega, donde el código de país NO se analizaba como booleano false en los analizadores YAML 1.1. Los analizadores modernos que apuntan a YAML 1.2 manejan esto correctamente, pero es un recordatorio útil de que la aparente simplicidad de YAML oculta una complejidad real del analizador.

  • Comentarios. # esto es un comentario — YAML admite comentarios inline y de línea completa. Solo esto lo convierte en la elección correcta para cualquier configuración que un humano va a mantener.
  • Anclas y alias. Define un bloque una vez con &anchor, reutilízalo en cualquier lugar con *alias. Esencial para configuraciones DRY de Kubernetes y pipelines CI de múltiples entornos.
  • Cadenas multilínea. Los escalares de bloque literal (|) y plegado (>) te permiten incrustar scripts de shell, consultas SQL, o datos de certificados limpiamente dentro de un archivo YAML.
  • Sangría legible. La estructura se define por espacios en blanco, lo que se mapea naturalmente a cómo los desarrolladores piensan sobre las jerarquías de configuración anidadas.
  • Debilidades. La sensibilidad a la sangría significa que un espacio mal colocado es un error de análisis. Los caracteres de tabulación están prohibidos. La coerción booleana de YAML 1.1 (Problema de Noruega, yes/no, on/off) ha causado bugs reales en producción. Los datos tabulares expresados como un array de objetos son más verbosos que incluso JSON.

TOON en Dos Oraciones

TOON es un formato de serialización compacto diseñado para pasar datos estructurados hacia y desde los grandes modelos de lenguaje, donde cada token cuesta dinero y el espacio de la ventana de contexto es finito. Su innovación clave es la notación tabular: para datasets donde cada registro comparte los mismos campos, las claves se declaran una vez en un encabezado y se omiten de cada fila siguiente — que es lo opuesto de lo que hacen JSON y YAML.

TOON no es un formato de configuración y nunca fue pensado para serlo. No hay sintaxis de comentarios. No hay anclas. No querrías editar a mano un dataset TOON de 500 filas más de lo que querrías editar a mano un archivo binario. Lo que TOON te ofrece es un formato que codifica la misma información que JSON en significativamente menos tokens — y menos tokens significa menores costos de API, datasets efectivos más grandes por prompt, y menos presión sobre los límites de la ventana de contexto. El tokenizador de OpenAI es la forma más rápida de ver esto en práctica: pega el mismo dataset en ambos formatos y compara.

  • Notación tabular. name[count]{col1,col2,...}: seguido de una fila de valores por línea. Las claves aparecen exactamente una vez independientemente del número de filas.
  • Notación de objeto. {key:value,key2:value2} — sin comillas en las claves, sin espacios adicionales.
  • Análisis sin ambigüedad. Sin coerción booleana, sin sensibilidad a la sangría, sin divergencia de versión de especificación.
  • Sin sintaxis de comentarios. TOON no tiene mecanismo para comentarios inline — por diseño. Es un formato de datos, no un formato de documento.
  • Debilidades. Herramientas de nicho, sin historial de edición humana, no apropiado para ningún archivo que un desarrollador abra y edite directamente.

Lado a Lado: Los Mismos Datos en el Elemento de Cada Formato

La comparación más honesta muestra cada formato haciendo lo que realmente hace bien — sin forzar una confrontación directa donde uno es claramente la herramienta incorrecta.

Primero, un manifest de Deployment de Kubernetes. Este es el territorio de YAML: un archivo de configuración mantenido por humanos con comentarios, anclas para valores compartidos, y anidación profunda que mapea a la jerarquía lógica de un objeto Kubernetes:

yaml
# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  namespace: production
  labels:
    app: payments-service
    version: "2.4.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-service
  template:
    metadata:
      labels:
        app: payments-service
    spec:
      containers:
        - name: payments-service
          image: registry.example.com/payments-service:2.4.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              valueFrom:
                secretKeyRef:
                  name: payments-db-secret
                  key: host
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Escribir eso en TOON sería inútil — no son datos tabulares, serán editados por humanos, y se benefician de comentarios que explican valores no obvios. YAML es la herramienta correcta aquí, y no hay competencia.

Ahora los mismos datos en el territorio de TOON: un dataset de usuarios que se pasa a un LLM para análisis. Aquí es donde la notación tabular de TOON hace el trabajo:

text
users[12]{id,email,plan,mrr,country,signupDate,churned}:
  1001,[email protected],pro,99.00,US,2024-01-15,false
  1002,[email protected],starter,19.00,GB,2024-02-03,false
  1003,[email protected],enterprise,499.00,DE,2023-11-20,false
  1004,[email protected],pro,99.00,CA,2024-03-10,true
  1005,[email protected],starter,19.00,AU,2024-01-28,false
  1006,[email protected],pro,99.00,US,2023-12-05,false
  1007,[email protected],enterprise,499.00,FR,2024-02-14,false
  1008,[email protected],starter,19.00,IN,2024-03-22,true
  1009,[email protected],pro,99.00,US,2024-01-09,false
  1010,[email protected],enterprise,499.00,JP,2023-10-31,false
  1011,[email protected],starter,19.00,BR,2024-04-01,false
  1012,[email protected],pro,99.00,US,2024-02-19,true

Escribir eso como YAML — un array de 12 objetos, cada uno con 7 claves — repetiría los 7 nombres de clave 12 veces. Eso es 84 declaraciones de clave para 84 valores. TOON declara cada clave una vez.

Dónde YAML Supera a TOON Siempre

Cualquier archivo que un ser humano abra, lea y edite pertenece a YAML (o JSON, para casos más simples). Las ventajas decisivas son los comentarios y las anclas — dos características que TOON simplemente no tiene.

  • Pipelines CI/CD. GitHub Actions, GitLab CI, CircleCI — todos nativos de YAML. La capacidad de comentar un paso durante la depuración es genuinamente útil.
  • Kubernetes y Helm. Cada manifest, cada archivo de valores, cada template de chart. El sistema de anclas de YAML se usa activamente en charts de Helm complejos para evitar repetir configuraciones de entorno.
  • Docker Compose. Definiciones de múltiples servicios con comentarios que explican enlaces de puertos no obvios, montajes de volúmenes y configuraciones de red.
  • Archivos de configuración de aplicaciones. Configs estilo pyproject.toml, configuraciones de aplicaciones, indicadores de características con comentarios explicativos inline.
  • Cualquier archivo en control de versiones que los humanos revisan en PRs. Los comentarios en la configuración YAML son parte de la documentación. TOON no puede participar en este flujo de trabajo en absoluto.
Nota sobre las anclas: Las anclas de YAML (&anchor) y los alias (*alias) están infrautilizados pero son poderosos. Una configuración de Kubernetes que comparte las mismas variables de entorno entre múltiples contenedores puede definirlas una vez con &common-env y referenciar el bloque con *common-env — manteniendo el archivo DRY sin ningún motor de plantillas. TOON no tiene mecanismo equivalente.

Dónde TOON Supera a YAML Siempre

Cualquier dato que se genera programáticamente y se pasa a un LLM pertenece a TOON. YAML es en realidad peor que JSON para este caso de uso — su sintaxis cargada de sangría y nombres de clave repetidos agregan tokens sin agregar ninguna información que el modelo necesita.

  • Cargas útiles de prompt de LLM. Alimentar un dataset a GPT-4o, Claude, o Gemini para análisis, clasificación o enriquecimiento. La notación tabular de TOON reduce el recuento de tokens en un 40–60 % en comparación con JSON, y comparado con YAML la brecha es aún mayor.
  • Instrucciones de salida de LLM. Instruir a un modelo para que responda en TOON produce una salida más corta y barata. La salida YAML de un LLM es verbosa y sensible a la sangría — un espacio mal alineado y el análisis se rompe.
  • Datasets generados programáticamente. Si tu código está construyendo los datos, debería construir TOON. No hay editor humano para beneficiarse de comentarios o sangría legible.
  • Pipelines de procesamiento por lotes de alto volumen. ¿Procesando 10,000 registros a través de un LLM por día? Una reducción del 50 % en tokens es una reducción del 50 % en esa línea de tu factura de API.
  • Presión de ventana de contexto. Cuando necesitas meter más datos dentro del límite de contexto de un modelo, TOON te permite meter más filas al mismo costo de tokens.

La Realidad del Conteo de Tokens

Aquí está el mismo dataset de 10 filas en tres formatos. Los números son aproximados pero consistentes con lo que el tokenizador de OpenAI reporta para la tokenización de GPT-4o.

Array de objetos YAML:

yaml
- id: 1
  username: alice_chen
  plan: pro
  mrr: 99.00
  country: US
- id: 2
  username: bob_martin
  plan: starter
  mrr: 19.00
  country: GB
- id: 3
  username: carol_white
  plan: enterprise
  mrr: 499.00
  country: DE
- id: 4
  username: dan_patel
  plan: pro
  mrr: 99.00
  country: CA
- id: 5
  username: eve_torres
  plan: starter
  mrr: 19.00
  country: AU
- id: 6
  username: frank_liu
  plan: pro
  mrr: 99.00
  country: US
- id: 7
  username: grace_kim
  plan: enterprise
  mrr: 499.00
  country: FR
- id: 8
  username: henry_obi
  plan: starter
  mrr: 19.00
  country: IN
- id: 9
  username: iris_novak
  plan: pro
  mrr: 99.00
  country: US
- id: 10
  username: james_sato
  plan: enterprise
  mrr: 499.00
  country: JP

Notación tabular TOON, los mismos datos:

text
users[10]{id,username,plan,mrr,country}:
  1,alice_chen,pro,99.00,US
  2,bob_martin,starter,19.00,GB
  3,carol_white,enterprise,499.00,DE
  4,dan_patel,pro,99.00,CA
  5,eve_torres,starter,19.00,AU
  6,frank_liu,pro,99.00,US
  7,grace_kim,enterprise,499.00,FR
  8,henry_obi,starter,19.00,IN
  9,iris_novak,pro,99.00,US
  10,james_sato,enterprise,499.00,JP
Conteos de tokens aproximados para este dataset: YAML ≈ 290 tokens. JSON (array de objetos equivalente) ≈ 230 tokens. TOON ≈ 115 tokens. YAML no es solo peor que TOON — es peor que JSON para datos tabulares, porque su sintaxis de sangría agrega tokens que las llaves de JSON no agregan. TOON gana por aproximadamente 2.5× sobre YAML y 2× sobre JSON en esta forma de datos. Verifica con el tokenizador de OpenAI.

La razón por la que YAML rinde peor que JSON en datos tabulares es estructural: YAML usa una línea por par clave-valor con sangría, por lo que un objeto de 5 campos cuesta 5 líneas más el marcador de lista. JSON al menos envuelve todo el objeto en un conjunto de llaves. TOON elimina completamente la repetición de claves — las claves aparecen una vez, los valores se empaquetan en filas. Los ahorros se acumulan con el número de filas y campos.

Usar TOON en Tu Código

El paquete @toon-format/toon maneja la codificación y decodificación:

bash
npm install @toon-format/toon
ts
import { encode, decode } from '@toon-format/toon';

// Your dataset — could come from a database query, API response, anywhere
const users = [
  { id: 1001, email: '[email protected]', plan: 'pro',        mrr: 99.00,  country: 'US' },
  { id: 1002, email: '[email protected]',   plan: 'starter',    mrr: 19.00,  country: 'GB' },
  { id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
  // ...more rows
];

// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
//   1001,[email protected],pro,99.00,US
//   1002,[email protected],starter,19.00,GB
//   1003,[email protected],enterprise,499.00,DE

const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.

Dataset:
${toonPayload}`;

// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }

Guía de Decisión

La elección entre YAML y TOON casi nunca es ambigua en la práctica:

  • Usa YAML si un humano leerá o editará el archivo — pipelines CI/CD, manifests de Kubernetes, Docker Compose, configuración de aplicaciones, playbooks de Ansible.
  • Usa YAML si necesitas comentarios inline para explicar valores no obvios.
  • Usa YAML si necesitas anclas y alias para mantener una configuración compleja DRY.
  • Usa YAML si estás trabajando con una herramienta que espera YAML por convención (Helm, GitHub Actions, k8s kubectl apply).
  • Usa TOON si los datos van en un prompt de LLM — especialmente datos tabulares con múltiples filas.
  • Usa TOON si le estás pidiendo a un LLM que devuelva datos estructurados y quieres una salida más corta y barata.
  • Usa TOON si el conteo de tokens importa — pipelines de alto volumen, datasets largos, presión de ventana de contexto.
  • Usa TOON si los datos se generan programáticamente y ningún humano los editará directamente.
  • Usa JSON (no YAML ni TOON) si estás construyendo una API REST, almacenando datos en una base de datos, o integrando con herramientas de terceros que esperan JSON.

En Resumen

YAML y TOON ocupan posiciones completamente diferentes en tu stack. YAML pertenece a tu repositorio junto a tu código — archivos de configuración, definiciones de pipeline, manifests de infraestructura. TOON pertenece en el límite entre tu aplicación y las APIs de LLM, donde convierte tus datos estructurados en la representación más eficiente en tokens antes de enviar y convierte la respuesta del modelo de vuelta al salir. No hay superposición significativa entre estos trabajos, por lo que la pregunta no es "cuál es mejor" sino "cuál pertenece aquí".

Si estás trabajando con TOON, el Formateador TOON y el Validador TOON son la forma más rápida de inspeccionar y verificar cadenas TOON. El convertidor de JSON a TOON convierte cargas útiles JSON existentes en TOON para uso con LLM, y el convertidor de TOON a JSON maneja el viaje de regreso cuando un modelo responde en TOON y tu sistema downstream espera JSON. Ver también el artículo de Wikipedia sobre YAML para una historia concisa del formato y un resumen de sus casos extremos conocidos.

← All TOON articles Browse all categories →