Convertir TOML a YAML

Los datos declarados de un proyecto viven cada vez más en un archivo TOML: el nombre del paquete, las versiones admitidas de Python o de Rust, las banderas de características, el conjunto de dependencias. Lo que consume esos datos es, con la misma insistencia, YAML: un flujo de GitHub Actions, un archivo de valores de Helm, un conjunto de variables de Ansible, un bloque de servicio de docker-compose. Nadie eligió esta división; es lo que dos ecosistemas decidieron por separado.

Por eso el trabajo casi nunca es una migración, sino una transcripción: llevar los valores a la sintaxis YAML con exactitud y después mover a mano las partes que hacen falta a un archivo que tiene su propia forma obligatoria. La distinción importa porque cambia qué significa «salida correcta». El resultado no tiene que ser un flujo válido. Tiene que ser una representación fiel de la que puedas copiar sin volver a teclear un número de versión.

TOML es raro entre los formatos de configuración por tener tipos de fecha de verdad, escritos sin comillas: `lanzamiento = 2026-03-01T08:00:00Z`, `dia = 2026-03-01`, `a_las = 08:00:00`. Llegan al YAML de la misma manera —`lanzamiento: 2026-03-01T08:00:00.000Z`, `dia: 2026-03-01`, `a_las: 08:00:00.000`—, sin comillas, que es la forma que YAML reserva para una marca de tiempo. Convierte el mismo manifiesto a JSON y obtendrás exactamente los mismos caracteres dentro de un par de comillas, porque JSON tiene un solo tipo escalar para el texto y nada más que ofrecer.

Lo que eso te compra depende por entero del cargador, y conviene saberlo antes de apoyarse en ello. Lee la salida con la misma biblioteca que la escribió, que sigue el esquema básico de YAML 1.2, y todos esos valores vuelven como cadenas: 1.2 no tiene resolutor de marcas de tiempo. Léela con PyYAML o con Psych de Ruby, ambos todavía en YAML 1.1, y las dos primeras se convierten en fechas mientras que `a_las: 08:00:00.000` se resuelve como el número sexagesimal 28800. Un desplazamiento horario además se normaliza a UTC por el camino, así que `2026-03-01T08:00:00+02:00` vuelve como las 06:00:00Z. Si una fecha tiene que seguir siendo una fecha, decláralo en el destino en lugar de fiarte de la forma del archivo.

Una cabecera `[paquete]` se convierte en una clave de primer nivel con sus valores indentados dos espacios debajo. Una cabecera `[tool.black]` se convierte en `tool:` conteniendo `black:` conteniendo los ajustes, porque una cabecera con puntos es anidamiento y no un nombre que lleva puntos. Las claves punteadas se comportan igual: `a.b = 1` pasa a ser `a:` con `b: 1` dentro.

El orden es el que vio el analizador, y nada en esta conversión ordena nada. Para TOML eso significa que los valores sueltos de la cabecera del archivo van primero y cada tabla sigue en el orden en que fue escrita, lo cual suele leerse bien porque el propio TOML exige que las claves de raíz precedan a la primera cabecera de tabla. Lo que sí se mueve es lo que estuviera expresado con claves punteadas repartidas por el archivo: en el YAML se reúne todo bajo un mismo padre, que es más legible y no es lo que ponía el texto de origen.

Éste es el verdadero cambio de régimen y es fácil pasarlo por alto porque la salida se parece muchísimo a la entrada. En TOML, `activo = true` es un booleano porque lo dice la sintaxis, y `version = "1.0"` es una cadena porque va entre comillas: no se infiere nada y nada se puede malinterpretar. En YAML, un escalar sin comillas es lo que el analizador decida que es.

Por eso el escritor pone comillas donde hacen falta: una cadena compuesta de dígitos sale entrecomillada, de modo que `version = "1.0"` sigue siendo `version: "1.0"` y no el número 1. Lo que no entrecomilla es `NO`, `sí` escrito como `yes`, `on` y `off`, porque bajo YAML 1.2 ésas son cadenas corrientes y el archivo está escrito para un analizador 1.2. Cárgalo con PyYAML o con Psych y se convertirán en booleanos. Quien escribe TOML nunca ha tenido que pensar en esto, y por eso merece un párrafo.

Un bloque `[[bin]]` o `[[tool.poetry.packages]]` repetido es la forma de lista de registros de TOML, y se convierte en la forma que todo el mundo escribe a mano en YAML: un guion por entrada y las claves indentadas debajo. Los arrays normales se comportan igual, una línea con guion por elemento, y un array de escalares escrito en línea dentro del TOML sale como lista en bloque en vez de con sintaxis de flujo.

Esa forma en bloque es la que documentan la mayoría de las herramientas de YAML y la que enseñan casi todos los ejemplos, así que las entradas suelen pegarse en un flujo o en un archivo de valores sin reformatear nada. Si el destino quiere de verdad estilo de flujo —una línea de matriz escrita como `[3.11, 3.12, 3.13]`—, eso es una edición manual, y pequeña.

Una cadena TOML entre comillas triples que contenga un script, una descripción o un fragmento de licencia conserva su estructura de líneas. El escritor la emite como escalar en bloque —la clave, una barra vertical y las líneas de verdad indentadas debajo— en lugar de meterla en una sola línea llena de secuencias de escape.

Los valores largos de una sola línea se tratan distinto: una cadena sin saltos pero con mucha longitud se pliega en líneas de continuación alrededor de las ochenta columnas, y YAML lee esos pliegues de vuelta como espacios, así que el valor no cambia. Sí implica que una URL larga puede aparecer partida en dos líneas del archivo, lo cual desconcierta pero no daña; copiar el valor de la estructura ya cargada, y no del texto, elimina cualquier duda.

TOML y YAML aceptan comentarios con almohadilla, y un manifiesto suele estar lleno de ellos: por qué una dependencia está fijada a una versión concreta, cuál de dos ajustes es intencionado, de dónde salió un número mágico. Nada de eso llega al resultado, porque el lector descarta los comentarios al entrar y el escritor no tiene ninguno que colocar al salir.

Para un fragmento que vas a pegar en otro sitio, eso no tiene importancia. Para algo que pienses conservar, es justamente la razón por la que el TOML sigue siendo la fuente de verdad y el YAML es generado: dos archivos con los mismos valores y sólo uno con los motivos es un problema de mantenimiento esperando a que lo herede alguien. Si el YAML tiene que acabar en el repositorio, escribe arriba un comentario corto diciendo de qué manifiesto salió y cómo se regenera.

La salida emplea un subconjunto llano del lenguaje, y saber qué partes faltan ahorra tiempo al leerla. No hay anclas ni alias: una subtabla repetida aparece dos veces entera en lugar de una vez con una referencia, porque los valores analizados son objetos distintos y nada los deduplica. No hay ningún nulo, porque TOML no tiene nulo que convertir. No hay etiquetas, ni tipos explícitos, ni separador de documentos: el archivo es un documento único.

Si el destino espera algo de eso, lo estás añadiendo a mano. Un conjunto de variables de Ansible que dependa de etiquetas de vault, o un archivo de valores de Helm construido alrededor de anclas para no repetirse, es un archivo al que esta conversión alimenta y no uno que produzca. No es una limitación de YAML: es que el manifiesto nunca expresó esas cosas y nada puede inventarlas.

La comprobación más barata es un viaje de ida y vuelta. Carga la salida con lo que vaya a cargarla de verdad y compara un puñado de valores contra el manifiesto: la versión, una fecha, cualquier cosa que pareciera un número y deba ser texto, y cualquier valor que sea una palabra suelta. Esas cuatro categorías cubren casi todo lo que puede salir mal en silencio.

`yq eval . salida.yaml` reformatea y avisa si hay un error de sintaxis, y una línea de Python con `yaml.safe_load` te enseña qué cree un cargador de YAML 1.1 que dice el archivo, que es la versión de la verdad que importa si el destino es Ansible o una herramienta de Kubernetes de hace unos años. Hacerlo una vez es más rápido que depurar una tubería que se ejecutó con `version: 1` donde querías `"1.0"`.

En esta pestaña, con JavaScript corriente. No se sube nada, no hay ningún motor que descargar antes, no hay cuenta ni cupo diario. La forma de confirmarlo es abrir la pestaña de red y convertir algo, no creerse este párrafo.

Los manifiestos son lo bastante pequeños como para que el tope de 100 MB por archivo sea teórico, pero no siempre son públicos. La lista de dependencias de un repositorio privado nombra paquetes internos y registros internos, y un bloque `[tool]` a veces lleva nombres de máquina o rutas que dicen de una organización más de lo que nadie pretende. Convertir en local significa que nada de eso es una divulgación, y en un proyecto con cláusula de confidencialidad esa diferencia es la que decide si puedes usar la herramienta o no.