JSON vs YAML vs TOML: los formatos de configuración comparados con honestidad

Todo desarrollador acumula opiniones sobre los formatos de configuración, normalmente ganadas a base de una cicatriz de indentación YAML. Los tres formatos dominantes coexisten por razones reales, y moverse entre ellos es una tarea diaria — los pipelines de CI quieren YAML, las configuraciones de app quieren TOML, las APIs quieren JSON. Aquí va la comparación honesta y las trampas de conversión que conviene conocer antes de pulsar el botón.

La versión de una línea

• JSON (2001) — el intercambio de datos universal. Máquina primero, verboso, cero comentarios.
• YAML (2001) — el peso pesado legible por humanos. Guiado por indentación, rico en funciones, ocasionalmente traicionero.
• TOML (2013) — el formato de archivos de configuración con dignidad. Explícito y sin ambigüedad, hecho para archivos que una persona mantiene a mano.

JSON: la columna vertebral del intercambio

JSON ganó porque es aburrido: una especificación de una página, un parser en todos los lenguajes y una estructura que mapea directamente a los tipos de datos de programación. Por eso es el idioma de las APIs, los registros de paquetes y las herramientas de navegador — en cualquier lugar donde una máquina habla con otra máquina.

Sus límites son humanos. Sin comentarios (la queja eterna — cada workaround, desde claves "//" hasta entradas muertas de configuración, es una cicatriz), comillas y llaves obligatorias, y cadenas multilínea que se ponen feas rápido. JSON está optimizado para escribirlo programas, y lo notas al instante cuando te obligan a editar a mano un package-lock.json de 200 líneas.

Un detalle que merece respeto: el modelo de números de JSON. Los enteros grandes por encima de 2^53 pierden precisión en herramientas JavaScript (los IDs de otros sistemas se corrompen en silencio), y las claves duplicadas son técnicamente comportamiento indefinido — la mayoría de parsers conservan la última, lo que puede esconder datos en la conversión.

YAML: potente y ocasionalmente peligroso

La propuesta de YAML es la legibilidad: estructura anidada por indentación, listas con guiones, puntuación mínima. Es la lengua nativa de Kubernetes, GitHub Actions y todos los sistemas de CI — por eso «convertir YAML a JSON» suele significar «hacer legible por máquinas un archivo de CI».

Pero YAML es un superset con una cola larga de funciones, y la cola muerde:

1. El problema de Noruega. country: NO se parsea como booleano false. version: 1.20 se parsea como el número 1,2, estropeando versiones de software en silencio. Los escalares sin comillas sufren inferencia de tipos de formas que sorprenden a todo el mundo tarde o temprano.
2. Anclas y alias (&anchor, *alias) permiten que un bloque referencie otro — brillante para desduplicar pipelines grandes, y un conversor que no los expande produce JSON estructuralmente incorrecto.
3. Archivos multidocumento (--- separando documentos) y cadenas multilínea (la familia | / >) llevan semántica que los conversores ingenuos aplanan.
4. La indentación ES la estructura — pega un bloque desde el chat y puedes romper o fusionar niveles de anidación en silencio, de formas que aún parsean como YAML válido. Esta es la cicatriz que todo usuario de YAML tiene.

Manejado por un parser de verdad, YAML es excelente para su nicho: archivos de orquestación grandes mantenidos por humanos. Manejado por regex, es cómo ocurren los incidentes.

TOML: el archivo de configuración que se porta bien

TOML apostó al revés: hacer explícita cada estructura. Las tablas son [secciones], los pares clave-valor son obvios, las fechas tienen tipo nativo, y hay exactamente una forma de escribir cada cosa — sin sorpresas de inferencia, sin whitespace-como-estructura. El ecosistema de Rust, el pyproject.toml de Python y Cargo se estandarizaron en él por una buena razón: un archivo TOML leído por tres parsers distintos es el mismo archivo.

Su coste es la verbosidad en profundidad: los datos profundamente anidados se vuelven cadenas de cabeceras [a.b.c], y las estructuras grandes repetitivas se hacen tediosas. TOML optimiza para archivos que humanos editan con cuidado, no para payloads de datos arbitrarios — que es exactamente lo que es la configuración.

Convertir entre ellos — las trampas

La conversión entre los tres es una negociación con fronteras con pérdida, y saber qué dirección es «segura» ahorra horas de depuración:

• YAML → JSON es la dirección más segura si el conversor expande anclas/alias y multidocumentos correctamente. La trampa: las cadenas sin comillas de YAML como on, off, yes — un conversor con inferencia de tipos convertirá alegremente el nombre de tu rama en true.
• JSON → YAML es estructuralmente sin pérdida (YAML puede representar todo JSON — JSON es técnicamente YAML válido), pero puedes adquirir las rarezas de inferencia de YAML al reparsear: pon comillas a todo lo que parezca número, versión o palabra booleana.
• JSON → TOML choca con el tipado estricto de TOML: los arrays de tipos mezclados de JSON ([1, "a", true]) son inválidos en TOML — un conversor debe o dar error con honestidad o convertir valores a cadena (lo que corrompe los tipos aguas abajo). El JSON profundamente anidado también aterriza como cadenas incómodas de cabeceras.
• TOML → JSON es limpio — la explicitud de TOML mapea directamente; el único matiz es el tipo datetime nativo de TOML, que JSON representa como cadena (consérvalo en formato ISO o pierde la semántica).

Nuestros conversores (JSON a YAML, YAML a JSON, JSON a TOML, y las guías de formato de JSON, YAML, TOML) parsean con parsers de verdad — nunca regex — y todos corren en local en el navegador, algo que aquí importa más que de costumbre: los archivos de configuración contienen habitualmente topología de infraestructura, hostnames internos y secretos. Una web de «pega tu YAML de Kubernetes» es un vector de filtración; convertir en tu navegador no lo es.

¿Cuál deberías usar?

• Construyes una API o cualquier cosa máquina-a-máquina → JSON, sin debate.
• CI/CD, Kubernetes, cualquier cosa del ecosistema DevOps → YAML — el ecosistema lo decidió por ti.
• Configuración de aplicación mantenida a mano por un humano (proyectos Rust, Python, Go) → TOML.
• Convertir entre ellos → usa parsers reales, pon comillas a los escalares ambiguos y revalida los tipos al otro lado.

FAQ

¿YAML es JSON válido?

No — pero al revés sí: todo documento JSON es YAML válido (JSON era un subconjunto de YAML en sus primeras versiones y sigue siendo parseable por los parsers YAML modernos). Esa calle de sentido único es la razón de que JSON → YAML «funcione sin más» y el sentido contrario necesite un parser de verdad.

¿Por qué cambia mi número de versión al convertir YAML?

YAML infiere tipos en escalares sin comillas: 1.20 se convierte en el float 1,2, 1.0 puede volverse 1. Pon comillas a las cadenas de versión (version: "1.20") en el origen, o usa un conversor que conserve el texto original de los escalares.

¿TOML puede representar todo lo que JSON?

No. TOML prohíbe los arrays de tipos mezclados, y la profundidad de anidación arbitraria de JSON es legal pero dolorosa como cadenas de cabeceras [a.b.c.d]. Los conversores o rechazan esas estructuras o fuerzan los tipos — lee lo que hizo tu conversor en vez de asumir un mapeo limpio.

¿Para qué necesita comentarios un formato de configuración?

Porque la configuración codifica decisiones («este timeout es de 30s por el p99 del upstream»), y las decisiones sin contexto las «arregla» la siguiente persona. El diseño sin comentarios de JSON es su característica más resentida; YAML y TOML tienen ambos comentarios de primera clase.