Convertir YAML a TOML

Los valores sueltos y los arrays se escriben primero, y cada mapeo anidado aparece después como su propia cabecera entre corchetes. Anidar tres niveles produce una única cabecera con puntos en vez de tres bloques anidados, así que un mapeo escrito como tool, luego ruff, luego un ajuste, sale como una cabecera [tool.ruff] con el ajuste debajo.

Ese aplanado de cabeceras es la diferencia visible entre los dos formatos. YAML expresa la profundidad con la sangría y puede anidar sin límite antes de volverse ilegible; TOML expresa la profundidad en el propio nombre de la cabecera y se mantiene legible hasta cuatro niveles porque la ruta completa aparece escrita en cada bloque. Es la apuesta con la que se diseñó el formato, y para un archivo de configuración de proyecto suele ser la acertada.

Una línea escrita como clave: sin nada detrás es YAML válido y se interpreta como nulo. TOML no tiene un valor nulo — la especificación sencillamente no lo define — así que el escritor omite la clave. Sin error, sin marcador, sin comentario: la clave estaba en tu YAML y no está en tu TOML.

Esto importa más de lo que parece porque las claves vacías son un recurso deliberado en YAML. Marcan un ajuste como presente pero sin definir, reservan un hueco que alguien va a rellenar más tarde, y documentan que una opción existe. Toda esa información se pierde. Busca en el archivo de origen las líneas que terminan en dos puntos antes de convertir y decide para cada una si necesita un valor explícito, una cadena vacía o un comentario en el TOML.

El mismo valor nulo dentro de un array se comporta de otra forma: el escritor se niega, y la conversión falla con un mensaje que dice que un array no puede contener valores nulos o indefinidos. No se produce nada.

Es el mejor de los dos comportamientos, y la diferencia es deliberada, no un descuido. Quitar una clave de una tabla deja el resto de la tabla con sentido; quitar un elemento de un array desplaza todos los que venían después, lo que convierte una lista ordenada en otra distinta. Negarse es la única respuesta segura, y significa que un YAML con un guion suelto sin nada detrás avisa en vez de convertirse en algo sutilmente incorrecto.

TOML agrupa por tabla. Todo lo que pertenece a una tabla tiene que aparecer después de su cabecera y antes de la siguiente, así que el escritor emite primero cada valor suelto y cada array, y después cada bloque anidado por turnos. Un archivo de integración continua convertido de esta forma pone su lista de etapas arriba del todo y las definiciones de trabajos debajo como tablas, sin importar el orden que tuvieran en el YAML.

La consecuencia a prever está en el diff. Si el YAML está bajo revisión y el TOML lo va a sustituir en el mismo repositorio, el primer commit va a parecer una reescritura completa, porque lo es. Sube la conversión como su propio commit y sin nada más dentro, para que quien lo revise vea con claridad que solo cambió la sintaxis.

Un bloque literal — la barra vertical seguida de un guion de comandos con sangría, que es como casi todo pipeline de CI guarda sus pasos de compilación— se interpreta como una cadena con saltos de línea dentro, y el escritor la emite como una cadena TOML normal, entre comillas, con los saltos convertidos en la secuencia de escape correspondiente. Un guion de diez líneas se convierte en una sola línea muy larga.

TOML tiene una sintaxis de cadena multilínea con comillas triples que dejaría ese guion legible, y el escritor no la usa. Esa es una conversión que se hace a mano: localiza los valores con saltos escapados y reescribe cada uno con comillas triples. Merece la pena hacerlo con cualquier valor que un humano vaya a volver a editar, y no tanto con uno que solo lee un programa.

TOML es el único formato de esta familia con fechas de primera clase: fecha y hora con huso, fecha y hora locales, fecha local y hora local forman todos parte de la especificación, y un analizador TOML los devuelve como fechas y no como texto. Es el motivo principal por el que un proyecto elige TOML antes que JSON.

Esta conversión no te los entrega. YAML 1.2 trata un valor sin comillas como 2024-01-02 como una cadena de texto, así que llega al TOML como "2024-01-02" con las comillas puestas. Quitar esas comillas después es todo el trabajo y lleva segundos; dejarlas puestas también funciona y simplemente significa que tu TOML guarda texto donde podría guardar una fecha. Lo mismo pasa con un entero escrito con punto decimal: un valor YAML de 1,0 se convierte en el entero TOML 1, porque el analizador ya lo había resuelto a un número entero antes de que el escritor lo viera.

El caso que más preocupa resulta ser el que mejor funciona. Una lista YAML cuyos elementos son mapeos —una lista de autores, una lista de binarios, una lista de trabajos— se convierte en un array de tablas TOML, con la cabecera de doble corchete repetida una vez por elemento. Es exactamente la forma que pide un pyproject.toml o un Cargo.toml para sus autores y sus objetivos de compilación.

Una lista en la raíz del YAML es la excepción. Los documentos TOML son siempre una tabla, así que un documento que es solo una lista se envuelve en una tabla con una única clave llamada items y la lista debajo. Si tu YAML es una secuencia en el nivel superior, decide tú el nombre de esa clave y añádelo al origen antes de convertir, para que el nombre signifique algo.

Las claves simples de TOML admiten letras, dígitos, guiones bajos y guiones. Cualquier otro carácter obliga a entrecomillar, y el escritor lo hace por ti: una clave con un punto sale como "date.timezone" con las comillas incluidas, y lo mismo pasa con una clave que contiene un espacio. Las claves entrecomilladas son TOML perfectamente válido.

También son una señal. Una clave entrecomillada con un punto dentro normalmente significa que el YAML estaba expresando estructura en el propio nombre de la clave en vez de en el anidado, y en TOML esa estructura suele quedar mejor como una tabla real. Dividirla o no es una decisión sobre tu configuración, no sobre la conversión, pero las comillas en la salida son un buen sitio por donde empezar a mirar.

Los dos formatos admiten comentarios y ninguno de los tuyos pasa al otro lado. El analizador los descarta al leer y el escritor no tiene nada que escribir. En un archivo de configuración de proyecto eso tiene un coste real: la nota que explica por qué una dependencia está fijada a esa versión, la alternativa comentada, la línea que dice a qué entorno se aplica un bloque.

La migración solo está terminada cuando esos comentarios vuelven a su sitio. Convierte, y después abre el YAML antiguo y el TOML nuevo uno al lado del otro para volver a poner cada nota donde corresponde. Son diez minutos en un archivo normal, y son la diferencia entre una configuración que alguien puede mantener y una que funciona pero nadie se atreve a tocar.

Un archivo YAML separado por marcas --- contiene varios documentos, y TOML describe exactamente una tabla, así que el analizador se detiene al encontrar el segundo documento en vez de elegir uno. La conversión falla en vez de convertir solo una parte y callarse el resto.

La forma de resolverlo es dividir el archivo antes de convertir, no cambiar ningún ajuste. Cada documento separado por guiones se convierte por su cuenta en su propio TOML, y si el resultado final tiene que quedar en un único archivo, unirlos después es una tarea de edición de texto, no de este conversor.

Todo el proceso ocurre en JavaScript dentro de esta página, así que un archivo con tokens, contraseñas o URLs de registros privados no sale de tu equipo en ningún momento. El límite del plan gratuito es de 100 MB, muy por encima de lo que pesa cualquier configuración real.

Antes de sustituir el YAML original, abre el TOML y busca tres cosas: las claves vacías que desaparecieron, los valores con comillas que deberían ser fechas o números, y las líneas que antes eran un guion de varios renglones y ahora son una sola línea larga. Son los tres puntos exactos que esta conversión avisa que no resuelve por sí sola.