YAML vs JSON vs TOML: fortalezas, casos de uso y las trampas de tipado implícito de YAML
El dominio de cada formato
Cada formato de serialización de datos domina en su propio terreno. JSON (JavaScript Object Notation, estandarizado como ECMA-404 y RFC 8259) es el lenguaje universal de las API HTTP: prácticamente todos los endpoints REST lo usan, cada lenguaje tiene un analizador JSON sin dependencias, y su gramática cabe en una sola página. YAML (YAML Ain't Markup Language) domina los archivos de configuración en herramientas DevOps — los manifiestos de Kubernetes, los flujos de trabajo de GitHub Actions, los playbooks de Ansible y los archivos Docker Compose son todos YAML. Sus cadenas multilínea y soporte de comentarios lo hacen mucho más cómodo que JSON para archivos que los humanos editan a diario. TOML (Tom's Obvious, Minimal Language) es la opción canónica para la configuración a nivel de proyecto: Cargo.toml para paquetes Rust, pyproject.toml para metadatos de construcción Python, y la configuración de sitios Hugo usan TOML. Sus literales fuertemente tipados y la sintaxis [section] hacen que los archivos de configuración sean fáciles de leer e imposibles de malescribir silenciosamente.
Estas diferencias de dominio no son accidentales — reflejan las prioridades de diseño de cada formato. JSON prioriza la interoperabilidad y el determinismo; YAML prioriza la legibilidad humana y la expresividad; TOML prioriza la seguridad de tipos y el análisis predecible. Entender estas prioridades facilita elegir la herramienta correcta y evitar importar los supuestos de un formato al espacio de problemas de otro.
La tipificación implícita de YAML: el problema de Noruega
El footgun más infame de YAML es su agresiva coerción de tipos implícita. En YAML 1.1 (la versión usada por la mayoría de los analizadores hasta hace poco, incluyendo PyYAML < 6.0 y Psych de Ruby antes de 4.0), un escalar sin comillas se prueba contra una secuencia de expresiones regulares para determinar su tipo. Las pruebas booleanas coinciden con yes, no, on, off, true, false — todas sin distinción de mayúsculas. Esto causó un error de integridad de datos en software que usa códigos de país ISO 3166-1 alpha-2: el código de Noruega es NO, que YAML 1.1 convierte silenciosamente al booleano false. El mismo problema afecta a fi (Finlandia → analizado como false en algunos analizadores), y cualquier clave de configuración cuyo valor sea exactamente yes o no sin comillas. Un mapeo como norway: NO se convierte en {norway: false} en tiempo de ejecución — sin error, sin advertencia.
YAML 1.2 (publicado en 2009, adoptado por ruamel.yaml y analizadores más recientes) restringió el conjunto booleano a solo true y false (distinguiendo mayúsculas), eliminando las variantes yes/no/on/off. Sin embargo, millones de archivos de producción y las herramientas que los leen aún se ejecutan contra analizadores YAML 1.1. La regla segura: siempre entrecomillar los valores de cadena que podrían malinterpretarse — códigos de país, palabras tipo bandera, cadenas que parecen numéricas. Use 'NO' no NO, '1e2' no 1e2 (que se convierte en el flotante 100.0), y '2024-01-01' no 2024-01-01 (que algunos analizadores convierten en un objeto fecha).
Otros problemas de YAML: tabuladores, anclas y el separador de documentos
La indentación es la sintaxis de YAML — y los tabuladores nunca son válidos como indentación YAML. La especificación prohíbe explícitamente los caracteres de tabulación en posiciones de indentación. Sin embargo, los tabuladores son invisibles en la mayoría de los editores por defecto, y un tabulador accidental produce un error de escáner que apunta al número de línea incorrecto en algunos analizadores. La solución es habilitar 'mostrar espacios en blanco' en el editor y configurarlo para expandir tabuladores a espacios en archivos .yaml. Una trampa relacionada es mezclar estilos de bloque y flujo: key: {a: 1, b: 2} es válido (mapeo de flujo como valor), pero indentar contenido de estilo flujo es sutil.
Los anclas YAML (&) y los alias (*) permiten reutilizar un nodo en todo el documento, lo cual es genuinamente útil para largos manifiestos de Kubernetes con especificaciones de contenedor repetidas. Pero también permiten ataques de expansión tipo 'billion laughs' en analizadores que no limitan la profundidad de alias. La mayoría de los analizadores de producción (PyYAML 5.1+, snakeyaml con SafeLoader) limitan la profundidad de alias; use siempre las API de carga segura. El separador de documentos --- permite múltiples documentos YAML en un archivo — kubectl apply -f depende de esto — pero algunos analizadores devuelven solo el primer documento a menos que se itere explícitamente, descartando silenciosamente el resto.
Los tipos explícitos de TOML y su ventaja con fechas
TOML asigna un tipo a cada valor a nivel de sintaxis, sin coerción implícita. Los enteros se escriben sin comillas (port = 8080), los flotantes requieren un punto decimal (timeout = 1.5), los booleanos son true o false en minúsculas, y las cadenas siempre necesitan comillas. Esto significa que un error tipográfico que produce una palabra sin comillas es un error de análisis, no un cambio de tipo silencioso — el analizador se niega a cargar el archivo en lugar de proceder con datos incorrectos. TOML 1.0 (lanzado en 2021) también especifica cuatro tipos de fecha y hora como literales de primera clase: offset_date_time (1979-05-27T07:32:00Z), local_date_time, local_date y local_time. Ningún otro formato de serialización importante trata las fechas como tipo integrado.
La sintaxis [table] y [[array of tables]] mapea limpiamente a objetos anidados y arrays de objetos. Un bloque [[servers]] seguido de otro bloque [[servers]] añade un segundo elemento al array servers — explícito, legible, e imposible de romper con un espacio extra. La contrapartida: TOML no admite anclas ni archivos multidocumento, por lo que jerarquías de configuración profundas con subárboles repetidos son más verbosas que sus equivalentes YAML.
La estrictez de JSON como característica
La gramática de JSON no tiene características opcionales, sin coerción de tipos y sin directivas a nivel de documento. Un analizador compatible que lea {"active": true} en cualquier plataforma producirá un booleano — no la cadena "true", no el entero 1. Este determinismo es la razón por la que JSON se convirtió en el formato de cable predeterminado para las API a pesar de ser menos amigable para los humanos que YAML. RFC 8259 refuerza la especificación: un texto JSON es un valor serializado. Las claves duplicadas dentro de un objeto son explícitamente 'no debería', y la codificación debe ser UTF-8 sin BOM.
La falta de comentarios es la queja más citada sobre JSON. Existen soluciones: JSON5 (un superconjunto con comentarios y comas finales), JSONC (usado en settings.json de VS Code), y simplemente eliminar las líneas // antes de analizar. La solución idiomática para la configuración que necesita comentarios es usar TOML o YAML para la autoría y JSON solo como formato de intercambio de máquinas, generado por un paso de construcción.
Elegir el formato correcto
La regla de decisión práctica es simple: JSON para cualquier dato que cruce un límite de servicio (API HTTP, colas de mensajes, configuración generada por código); YAML para archivos de configuración que los operadores editan a mano y que necesitan comentarios o cadenas multilínea — especialmente en ecosistemas que lo requieren (Kubernetes, GitHub Actions); TOML para configuración a nivel de proyecto donde la tipificación fuerte y la estructura de archivo plano son más importantes que la expresividad de YAML. En caso de duda, favorezca el formato que su ecosistema ya usa.
Si hereda un archivo de configuración YAML grande y sospecha errores de tipificación implícita, una auditoría rápida es ejecutarlo a través de un linter YAML 1.2 (yamllint, spectral) y buscar valores sin comillas que coincidan con patrones booleanos o numéricos. Para proyectos nuevos, considere agregar un esquema (JSON Schema funciona para los tres formatos a través de herramientas) — captura errores de tipo antes de que lleguen a producción. El conversor YAML / JSON / TOML de TeaFun le permite cambiar entre los tres en el navegador sin instalación.