La forma más rápida de convertir TOML a YAML es el comando yq -oy '.' file.toml. Para la conversión manual, mapee las cabeceras de tabla TOML [table] a bloques indentados en YAML, los arrays TOML a listas prefijadas con guión, y siempre cite las cadenas ambiguas para evitar el «Problema de Noruega».
Conversión rápida: uso del CLI yq
TOML (Tom’s Obvious, Minimal Language) alcanzó su versión 1.1.0 en diciembre de 2025, pero YAML sigue siendo el estándar para pipelines CI/CD y manifiestos de Kubernetes. La herramienta yq gestiona la conversión con un solo comando.
Instalar yq
| Plataforma | Comando |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python (pip) | pip install yq |
Se prefiere la versión basada en Go de Mike Farah por su velocidad. Como señala la documentación de yq de Mike Farah, la herramienta decodifica la estructura TOML y la recodifica como YAML limpio.
Ejecutar la conversión
Mostrar en la terminal:
yq -oy '.' your-config.toml
Guardar en archivo:
yq -oy '.' your-config.toml > your-config.yaml
El flag -oy establece el formato de salida en YAML. Gestiona pares clave-valor, tablas anidadas y arrays.
Mapa de traducción de sintaxis: estructura TOML a YAML
El desarrollador Drew DeVault ha señalado que, aunque TOML es popular, YAML maneja el anidamiento profundo de forma más limpia. Aquí está el mapeo exacto:
Tablas a claves indentadas
TOML usa cabeceras entre corchetes; YAML usa indentación.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
Diferencia crítica: En TOML, la indentación es cosmética. En YAML, la indentación es estructural — un solo espacio incorrecto rompe toda la configuración.
Arrays a listas prefijadas con guión
TOML: ports = [ 8000, 8001 ]
YAML:
ports:
- 8000
- 8001
Como explica Knightli.com, el «estilo de bloque» de YAML hace que las listas sean legibles, siempre que la alineación vertical sea consistente.
Tablas en línea y claves con punto
| Construcción TOML | Equivalente YAML |
|---|---|
[a.b.c] (cabecera con punto) |
a: → b: → c: (indentación anidada) |
point = { x = 1, y = 2 } (tabla en línea) |
point: → x: 1 → y: 2 |
Casos de uso reales
Configuración del sitio estático Hugo
Hugo acepta hugo.toml, hugo.yaml o hugo.json. La mayoría de los proyectos comienzan con TOML (el valor predeterminado) y luego migran a YAML cuando la configuración necesita alinearse con plataformas de despliegue como Netlify o GitHub Actions. Hammer Europe señala que el comando hugo lee estos archivos para determinar cómo el Markdown se convierte en un sitio en vivo.
Empaquetado Python: pyproject.toml a CI/CD YAML
La comunidad Python estandarizó pyproject.toml a través de PEP 518. Estas configuraciones frecuentemente necesitan traducción a YAML para los flujos de trabajo CI/CD de GitHub Actions. Para flujos de trabajo de agentes de IA, CocoIndex informa que las configuraciones YAML optimizadas pueden reducir el uso de tokens hasta en un 70 %.
El Problema de Noruega y otras trampas de conversión
El bug del código de país NO
En YAML 1.1, las cadenas sin comillas como NO, OFF y YES se convierten automáticamente en booleanos false o true. TOML evita esto exigiendo comillas para todas las cadenas. Al convertir, cite siempre los valores ambiguos:
| Valor | Interpretación YAML 1.1 | Solución |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
YAML 1.2 (la especificación actual) corrige la mayoría de estas coerciones, pero muchos analizadores aún usan el comportamiento 1.1 por defecto.
Errores de indentación
Los analizadores YAML rechazan archivos con indentación inconsistente. Errores comunes:
- Mezclar tabulaciones y espacios (YAML prohíbe las tabulaciones)
- Usar 3 espacios en un bloque y 2 en otro
- Elementos de lista desalineados
Generación asistida por IA
Herramientas como AgentBuilder permiten describir la configuración en lenguaje natural y producir YAML validado. Este ciclo de «describir → generar → validar» ayuda a evitar tanto los errores de indentación como el Problema de Noruega.
Conclusión
Use yq -oy '.' file.toml para la conversión automatizada. Para el trabajo manual, mapee las tablas TOML a la indentación YAML, los arrays a listas prefijadas con guión, y siempre cite las cadenas que puedan confundirse con booleanos. Después de cualquier conversión, valide la salida YAML antes de desplegar — un solo espacio desalineado o un NO sin comillas puede romper todo su pipeline.
FAQ
¿YAML soporta comentarios como TOML?
Sí. Ambos usan # para comentarios de una línea. Los comentarios en YAML pueden interferir con el análisis de cadenas multilínea, por lo que debe colocarlos en líneas separadas en caso de duda.
¿Qué es el «Problema de Noruega» en YAML?
En YAML 1.1, las cadenas sin comillas como NO (código de país de Noruega) se convierten automáticamente en el booleano false. TOML evita esto exigiendo comillas para todos los valores de cadena. Al convertir TOML a YAML, envuelva en comillas cualquier cadena potencialmente ambigua.
¿Qué formato maneja mejor el anidamiento profundo?
YAML. TOML requiere repetir cabeceras largas como [table.subtable.subsubtable] para cada nivel, lo cual se vuelve verboso. YAML representa la misma jerarquía con indentación — más compacto y legible en profundidad.
Deja una respuesta