TOML vs YAML: la misma configuración en tres formatos
TOML vs YAML
TOML vs YAML (y JSON): la misma configuración de tres formas | We.Inc
Compara TOML, YAML y JSON con los mismos archivos de configuración, lado a lado. Mira dónde se exige cada formato, de pyproject.toml y Cargo.toml a compose.yaml.
TOML es un formato parecido a INI pensado para archivos de configuración: cabeceras [table] explícitas, cadenas entre comillas, tipos de fecha reales y sangría sin significado. YAML depende de la sangría, deduce los tipos a partir de valores sin comillas y añade anclas y múltiples documentos. Para ajustes poco anidados, TOML es más difícil de romper; para anidamiento profundo, YAML se lee mejor.
TOML, YAML y JSON de un vistazo
TOML 1.0
YAML 1.2
JSON
Anidamiento
Cabeceras [table] y [a.b]
Sangría
Llaves
Comentarios
No tiene
Cadenas
Siempre entre comillas
Comillas opcionales
Siempre entre comillas dobles
Fechas y horas
Tipos integrados
No están en el esquema core de 1.2
Solo como cadenas
Distingue mayúsculas
Sí
Sí
Sí
Tipo de medio
application/toml
application/yaml
application/json
La mayoría de las veces no puedes elegir: el empaquetado de Python lee pyproject.toml, Rust lee Cargo.toml, y GitHub Actions y Docker Compose leen YAML. Cuando sí eliges, ver una misma configuración en los tres formatos deja claras las ventajas e inconvenientes. Elige un ejemplo abajo y compara.
Elige una de las configuraciones de ejemplo: ajustes de una aplicación, un manifiesto de paquete o una lista de servidores.
Lee los mismos datos en TOML, YAML y JSON uno junto a otro.
Fíjate dónde TOML necesita cabeceras ([[servers]]) y dónde YAML necesita una sangría cuidadosa.
Copia la versión que espere tu herramienta.
Las listas largas de registros parecidos son donde TOML se vuelve verboso: cada entrada necesita su propia cabecera [[name]].
TOML prohíbe definir dos veces la misma clave o tabla, lo que detecta errores de copiar y pegar que YAML puede dejar pasar según el parser.
Pon entre comillas los números de versión en YAML. TOML no tiene esa trampa porque allí un texto sin comillas nunca es una cadena válida.
Mantén un solo formato por repositorio cuando puedas. Mezclar formatos solo está bien cuando cada herramienta exige el suyo.
Preguntas frecuentes
¿Es TOML mejor que YAML?
Ninguno gana en todo. Las cabeceras explícitas y las comillas obligatorias de TOML hacen que los archivos de configuración pequeños y medianos sean difíciles de malinterpretar. YAML maneja el anidamiento profundo y las listas largas con menos ruido, a cambio de una sintaxis sensible a los espacios y de tipado implícito.
¿Por qué Python usa pyproject.toml?
Las guías de empaquetado de Python definen pyproject.toml con tres tablas: [build-system] para el backend de compilación, [project] para metadatos como el nombre, la versión y las dependencias, y [tool] para los ajustes de herramientas concretas como los linters.
¿Puede TOML representar todo lo que representa YAML?
No todo. TOML no tiene anclas ni alias, ni varios documentos por archivo, ni null, ya que cada clave debe recibir un valor. Para configuración eso rara vez importa, pero los datos YAML que dependen de esas funciones no se convierten de forma directa.
¿Qué formatos aceptan Docker Compose y GitHub Actions?
Ambos usan YAML. Los workflows de GitHub Actions viven en .github/workflows con extensión .yml o .yaml, y Compose busca compose.yaml por defecto, aunque sigue aceptando docker-compose.yaml para proyectos antiguos.
¿TOML admite cadenas multilínea?
Sí. Tres comillas dobles abren una cadena básica multilínea que admite secuencias de escape, y tres comillas simples abren una cadena literal multilínea que conserva el contenido exactamente como está escrito.
Dónde se exige cada formato
Los proyectos de Python se describen en pyproject.toml y los crates de Rust en Cargo.toml, así que TOML es la norma en esos ecosistemas. Hugo también acepta front matter en TOML entre líneas +++.
Los pipelines de CI, las configuraciones de contenedores y los manifiestos de despliegue tiran de YAML: los workflows de GitHub Actions y los archivos de Docker Compose son YAML, y la extensión que elijas es sobre todo cuestión de coherencia.
A qué renuncia TOML a cambio de seguridad
El objetivo de TOML, según su propia especificación, es corresponderse sin ambigüedad con una tabla hash. Eso significa no adivinar: el texto necesita comillas, los booleanos son solo true y false, y cada tabla se nombra en una cabecera.
El precio es la repetición en los datos anidados. Con tres niveles de profundidad, un archivo TOML repite la ruta de la tabla en cada cabecera, mientras que YAML simplemente sangra.
Qué archivos usan cada formato
Archivos de configuración habituales y el formato que exigen
Archivo
Formato
Lo lee
TOML
Las herramientas de compilación y empaquetado de Python
Cargo.toml
TOML
Cargo, el gestor de paquetes de Rust
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm y otros gestores de paquetes de Node
Front matter de Markdown
YAML (TOML con +++ en Hugo)
Generadores de sitios estáticos
Sintaxis de TOML que conviene conocer
Claves con puntos, tablas en línea y fechas
Las claves con puntos y las tablas en línea evitan cabeceras extra para grupos pequeños, y las fechas son valores tipados, no cadenas.
Una configuración en TOML, YAML y JSON
Elige un ejemplo. Las tres versiones contienen exactamente los mismos datos, así que puedes comparar cómo los escribe cada formato.
Configuración de ejemplo
TOML
YAML
JSON
En el ejemplo de ajustes de la aplicación, TOML guarda opens como una hora local real, mientras que las versiones YAML y JSON lo guardan como cadena.