Convertir YAML a XML

Cada clave se convierte en un elemento y su valor pasa a ser el contenido de ese elemento. Un mapeo anidado se convierte en un elemento anidado, con dos espacios de sangría por nivel, y un valor simple se convierte en texto entre una etiqueta de apertura y otra de cierre. El recorrido no tiene ninguna sorpresa, que es justo la propiedad que interesa cuando la salida tiene que encajar con una especificación que ha escrito otra persona.

Los valores se escriben siempre como texto, porque es lo único que puede contener un elemento XML. Un número YAML escrito 1,50 sale como 1.5, porque el analizador ya lo resolvió a número antes de que el escritor lo viera, y un booleano sale como la palabra true o false. Si el esquema que va a leer el resultado es estricto con la forma exacta de un valor —un decimal que debe conservar el cero final, una fecha que debe llevar zona horaria—, hay que poner ese valor entre comillas en el YAML como cadena de texto para que sobreviva tal cual.

XML exige exactamente un único elemento en el nivel más externo, y un documento YAML puede tener varias claves de primer nivel. La regla es: si hay una sola clave de primer nivel y no contiene una lista, se convierte en la raíz sea lo que sea lo que guarde. Así, un documento cuya única clave es pedido produce una raíz pedido; lo mismo pasa con uno cuya única clave es titulo con un valor simple debajo, que da el documento de una sola línea <titulo>hola</titulo>. Un documento con tres claves de primer nivel produce una raíz genérica que contiene tres hijos.

Una única clave de primer nivel que contiene una lista es el caso que sorprende. Recibe también la envoltura genérica, porque usar esa clave como raíz repetiría la etiqueta una vez por cada elemento y dejaría un documento con varios elementos externos, que no es XML válido. Cuando el nombre del elemento raíz importa —y en una integración siempre importa—, la solución es dejar en el YAML una única clave de mapeo de primer nivel con exactamente el nombre que espera el esquema, y meter todo lo demás debajo.

Una secuencia YAML bajo una clave produce esa clave repetida una vez por cada elemento. Tres pasos de compilación bajo una clave script se convierten en tres elementos script en fila, hermanos entre sí. Es el patrón XML más antiguo y más común, y es lo que espera un XSD escrito con maxOccurs sin límite.

No es el único patrón posible. Muchos esquemas quieren una etiqueta plural que contenga hijos en singular —un elemento dependencias que contiene varios elementos dependencia—, y este escritor no lo va a producir a partir de una lista sencilla. Se consigue escribiendo el YAML de esa forma: una clave dependencias cuyo valor es un mapeo con una única clave dependencia que guarda la lista. El anidado del origen es lo que produce el anidado en la salida, así que conviene dar forma al YAML pensando en el esquema en vez de esperar que el conversor adivine.

Un XML con todo en elementos funciona para datos y encaja mal con la mayoría de esquemas reales, que ponen identificadores, tipos y códigos de idioma en atributos. Dos nombres de clave dan ese control. Una clave que empieza por @ se convierte en un atributo del elemento que la contiene, con la @ eliminada, y una clave llamada #text pasa a ser el propio texto del elemento.

Escrito con un ejemplo: un mapeo YAML llamado pedido que contenga "@id" con valor 42, "@estado" con valor abierto, y una clave cliente, produce un elemento pedido con los atributos id y estado y un hijo cliente dentro. Combinar "@idioma" y "#text" en un mismo mapeo produce una sola etiqueta con un atributo y texto y sin hijos. Las dos claves necesitan comillas en el YAML, porque una @ al principio de un valor simple está reservada y una # arranca un comentario.

Los nombres de elemento XML admiten letras, dígitos, guiones bajos, guiones y puntos, y no pueden empezar por un dígito. Las claves YAML admiten casi cualquier cosa. Cada carácter que el escritor no puede usar se convierte en un guion bajo, y un nombre que empieza por un dígito recibe un guion bajo delante, así que "mi clave" se convierte en mi_clave y "2o" se convierte en _2o.

Esa sustitución pierde información y puede colisionar: dos claves que difieran solo en qué carácter prohibido contienen acaban con el mismo nombre de elemento. Los guiones y los puntos pasan sin tocar, así que una clave como trabajo-compilacion o herramienta.version se escribe tal cual la escribiste. Si el esquema de destino nombra los elementos con precisión, conviene renombrar las claves en el YAML antes de convertir en vez de arreglar el XML después.

No hay declaración XML, así que el archivo empieza directamente por la primera etiqueta. No hay DOCTYPE, ni declaración de espacio de nombres, ni referencia a un esquema. La salida es UTF-8 y está bien formada, y nada en ella dice a qué vocabulario pertenece.

En una integración esto suele ser un hueco que se rellena a mano, y es un hueco pequeño: una línea de declaración, un atributo xmlns en la raíz y una ubicación de esquema. El atributo xmlns es fácil de añadir en el propio origen, porque no es más que otra clave que empieza por @ dentro del mapeo de primer nivel del YAML — lo que significa que el espacio de nombres sobrevive a cada conversión futura en vez de tener que añadirse a mano cada vez.

Una clave YAML sin valor se convierte en un par de etiquetas vacío. XML no distingue eso de un elemento que contiene una cadena vacía, así que si el esquema trata de forma distinta lo ausente y lo vacío, mejor quitar la clave del YAML en vez de escribirla sin nada detrás.

Los símbolos & y < > y las comillas dobles en un valor se escapan, así que un texto con una URL con parámetros de consulta o un fragmento de código pasa sin romper el documento. Un bloque literal de varias líneas se escribe con sus saltos de línea intactos dentro del elemento, lo cual es XML válido — pero que el analizador que lo reciba conserve ese espacio en blanco depende de cada esquema, así que cualquier cosa sensible a espacios en blanco merece una sección CDATA que hay que añadir aparte.

En España, buena parte del intercambio administrativo obligatorio pasa por XML con un esquema estricto: la facturación electrónica entre administraciones sigue una especificación con campos, tipos y estructura fijados de antemano, no un formato libre. Cuando el origen de esos datos vive en YAML —una plantilla de línea de pedido, un catálogo de conceptos facturables— la conversión no da por sí sola un documento válido para ese esquema; da un árbol de etiquetas a partir de las claves que escribiste.

La distancia entre lo uno y lo otro se cierra en el YAML, no en el XML: nombrar cada clave exactamente como la nombra el esquema, usar @ para lo que el esquema espera como atributo, y quotar como texto cualquier valor cuya forma exacta importe. Hecho así, la salida ya llega con la forma correcta y la validación contra el esquema real es la única comprobación que queda pendiente.

XML es una recomendación del W3C desde 1998, y el motivo para escribirlo en vez de JSON es casi siempre el ecosistema que trae consigo antes que la propia sintaxis: un XSD para rechazar un documento mal formado antes de que llegue a una aplicación, XPath para extraer un valor concreto de un documento grande, XSLT para transformarlo, y las firmas digitales XML cuando la otra parte necesita demostrar que un documento no se alteró.

Nada de eso llega gratis con la conversión. Ejecuta el resultado contra el esquema de inmediato, con el primer archivo, antes de montar todo el proceso a su alrededor — un elemento que debería haber sido un atributo es un cambio de dos caracteres en el YAML y una tarde entera si lo descubres después de construir un pipeline sobre la forma equivocada.

Dos problemas de origen detienen la conversión en vez de degradarla. Un archivo con separadores --- contiene varios documentos YAML, y un archivo XML contiene uno solo, así que el analizador se niega en vez de elegir. Divídelo y convierte cada documento por separado. Una clave duplicada dentro del mismo mapeo también se rechaza, con el número de línea, lo cual es más estricto que algunas herramientas YAML y es lo correcto — una clave duplicada significa que uno de los dos valores se ha estado ignorando desde el día en que se añadió.

Los comentarios no detienen nada y tampoco sobreviven. Los dos formatos los admiten y ninguno de los tuyos pasa al otro lado, así que el XML que entregas lleva los datos y no el razonamiento detrás de ellos. Deja el YAML como la fuente de verdad, genera el XML como un producto derivado, y no edites nunca el XML directamente — ese es el uso para el que está pensada esta conversión.