La respuesta corta
Usa TOML para la configuración de aplicaciones, YAML cuando una herramienta lo exija (Kubernetes, pipelines de CI) y JSON para el intercambio de datos entre sistemas. Si solo recuerdas una frase de este artículo, que sea esa. Ahora el porqué.
JSON: el formato de datos disfrazado de configuración
Las fortalezas de JSON son la universalidad y la previsibilidad: cada lenguaje lo procesa y hay exactamente una forma de escribir cualquier cosa. Sus debilidades como formato de configuración escrito por humanos son reales: sin comentarios, comillas estrictas, las comas finales son fatales y las llaves muy anidadas son difíciles de escanear. JSON es la opción correcta cuando las máquinas escriben y leen el archivo (payloads de API, package.json, tsconfig). Para archivos que los humanos editan a diario, lucha contra ti. Valida el tuyo con nuestro validador JSON antes de culpar a tu app.
YAML: potente, popular y silenciosamente peligroso
YAML ganó DevOps porque es legible: compara un manifiesto de Kubernetes en YAML vs JSON y no hay discusión. Pero la flexibilidad de YAML es su trampa: espacios en blanco significativos, el infame problema de Noruega (NO interpretado como booleano falso) y múltiples formas de escribir lo mismo significan errores sutiles. Mi regla: usa YAML donde el ecosistema lo requiera, mantén los archivos pequeños y valida siempre. ¿Convertir entre ambos? Nuestros conversores JSON a YAML y YAML a JSON lo manejan en un pegado.
TOML: el formato de configuración bien hecho
TOML se diseñó desde cero para la configuración: sintaxis obvia, fechas nativas, comentarios, sin espacios en blanco significativos y una especificación lo bastante pequeña para implementarse correctamente. Por eso lo adoptaron Cargo, Poetry y Hugo. Su debilidad es la verbosidad para datos muy anidados y un soporte de ecosistema más débil en algunos lenguajes, pero para ajustes de aplicaciones es la opción mejor diseñada de las tres.
Comparación rápida
- Comentarios: YAML ✓, TOML ✓, JSON ✗
- Comas finales: todos ✗ (JSON el más estricto)
- Legibilidad humana: TOML ≥ YAML > JSON
- Universalidad para máquinas: JSON > YAML > TOML
- Trampas: YAML (espacios, coerción de tipos) > JSON (rigidez sintáctica) > TOML (menos)
Preguntas frecuentes
- ¿Puedo convertir mi configuración JSON a YAML o TOML?
- De JSON a YAML es sencillo con nuestro conversor: el modelo de datos se corresponde limpiamente. La conversión a TOML es más complicada porque la estructura de tablas de TOML no se corresponde 1:1 con el anidamiento arbitrario de JSON; para configuraciones complejas, una reescritura manual es más segura.
- ¿Por qué tantas herramientas siguen usando YAML a pesar de sus problemas?
- Inercia y legibilidad. Kubernetes, Ansible y GitHub Actions se estandarizaron en YAML desde temprano, y la ventaja de legibilidad para manifiestos grandes es genuina. El ecosistema no va a cambiar, así que lo pragmático es aprender los filos cortantes de YAML en lugar de luchar contra él.
- ¿JSON5 es un buen punto intermedio?
- JSON5 (comentarios, comas finales, claves sin comillas) corrige las mayores molestias de configuración de JSON y vale la pena considerarlo para proyectos nuevos donde controlas el parser. La adopción es la limitación: la mayoría de las herramientas esperan JSON estricto.