Converter YAML para XML

Cada chave vira um elemento e o valor dela vira o conteúdo desse elemento. Um mapa aninhado vira um elemento aninhado, indentado dois espaços por nível, e um valor simples vira texto entre a tag de abertura e a de fechamento. Nada nessa travessia é esperto demais, o que é exatamente a propriedade que você quer quando o resultado precisa bater com uma especificação escrita por outra pessoa.

Valores são escritos como texto, porque é tudo que um elemento XML consegue guardar. Um número YAML escrito como 1.50 sai como 1.5, já que o interpretador resolveu isso para um número antes do gravador ver, e um booleano sai como a palavra true ou false. Se o esquema de destino é rígido quanto à forma léxica, coloque o valor entre aspas no YAML para que ele sobreviva exatamente como estava.

O XML exige exatamente um elemento mais externo, e um documento YAML pode ter várias chaves de nível superior. A regra é: uma chave de nível superior vira a raiz, seja lá o que contenha, a menos que o que contenha seja uma lista. Um documento com três chaves de nível superior produz uma raiz genérica contendo três filhos.

Uma única chave de nível superior contendo uma lista é o caso que surpreende as pessoas. Também recebe o invólucro genérico, porque usar a chave como raiz repetiria essa tag uma vez por item e deixaria um documento com vários elementos mais externos, o que não é XML de jeito nenhum. Se o nome do elemento raiz importa — e numa integração sempre importa — dê ao YAML uma única chave de mapa de nível superior nomeada exatamente como o esquema espera.

Uma sequência YAML sob uma chave emite essa chave uma vez por item. Três comandos de build sob uma chave "script" viram três elementos script em sequência, irmãos entre si. Esse é o idioma XML mais antigo e mais comum, e é o que um XSD escrito com ocorrência ilimitada espera.

Não é o único idioma. Muitos esquemas querem um invólucro plural contendo filhos singulares, e este gravador não vai produzir isso a partir de uma lista simples. Você consegue isso escrevendo o YAML dessa forma: uma chave nomeada no plural cujo valor é um mapa com uma chave no singular guardando a lista. O aninhamento na origem é o que produz o aninhamento no resultado.

XML só de elementos serve bem para dado e serve mal para a maioria dos esquemas reais, que colocam identificador, tipo e código de idioma em atributo. Dois nomes de chave dão esse controle. Uma chave cujo nome começa com arroba vira um atributo no elemento envolvente, com a arroba removida, e uma chave chamada #text vira o texto próprio do elemento.

Escrito por extenso, um mapa YAML nomeado "pedido" contendo "@id" igual a 42, "@status" igual a aberto, e uma chave "cliente" produz um elemento pedido carregando os atributos id e status com um filho cliente dentro. Combinar "@lang" e "#text" num mapa só produz uma tag única com atributo e texto e sem filho.

Um nome de elemento XML permite letra, número, sublinhado, hífen e ponto, e não pode começar com número. Uma chave YAML permite praticamente qualquer coisa. Todo caractere que o gravador não consegue usar vira sublinhado, e um nome começando com número recebe um sublinhado na frente.

A substituição perde informação e pode colidir: duas chaves que diferem só no caractere proibido acabam com o mesmo nome de elemento. Hífen e ponto passam intactos, então uma chave assim é escrita exatamente como você digitou. Se o esquema de destino nomeia os elementos, renomeie as chaves do YAML para bater com isso antes de converter, em vez de consertar o XML depois.

Não há declaração de XML, então o arquivo começa na primeira tag. Não há tipo de documento, não há declaração de namespace e não há referência de esquema. O resultado é UTF-8 e bem formado, e nada nele diz a que vocabulário pertence.

Para uma integração isso costuma ser uma lacuna a fechar à mão, e é uma pequena: uma linha de declaração, um atributo de namespace na raiz, uma localização de esquema. O atributo de namespace é fácil de acrescentar na origem, já que é só mais uma chave começando com arroba no mapa de nível superior do YAML — o que significa que o namespace sobrevive a toda conversão futura em vez de ser reacrescentado toda vez.

Uma chave YAML sem valor vira um par de elemento vazio. O XML não consegue distinguir isso de um elemento contendo uma string vazia, então, se o esquema trata ausente e vazio de forma diferente, deixe a chave de fora do YAML em vez de escrevê-la sem nada depois.

E comercial, sinal de menor e maior e aspas duplas num valor são escapados, então texto contendo um endereço com parâmetro de consulta ou um trecho de código atravessa em segurança em vez de quebrar o documento. Um bloco de texto de várias linhas é escrito com as quebras de linha intactas dentro do elemento, o que é XML válido — mas se o interpretador de destino preserva esse espaço em branco depende do esquema.

O motivo de emitir XML em vez de JSON quase sempre é o ecossistema, não a sintaxe: XSD para rejeitar um documento malformado antes de chegar numa aplicação, XPath para puxar um valor de dentro de um documento grande, XSLT para reformar, assinatura digital XML onde uma contraparte precisa provar que um documento não foi alterado.

Nada disso vem de graça com a conversão. Rode o resultado contra o esquema imediatamente, no primeiro arquivo, antes de conectar o processo inteiro — um elemento que deveria ter sido um atributo é uma mudança de dois caracteres no YAML e uma tarde inteira perdida se você descobrir depois de montar um pipeline em torno da forma errada.

Dois problemas na origem param a conversão em vez de degradá-la. Um arquivo contendo separadores de documento guarda vários documentos YAML, e um arquivo XML guarda um só, então o interpretador recusa em vez de escolher. Divida e converta cada documento. Uma chave duplicada no mesmo mapa também é rejeitada, com o número da linha — mais rígido que algumas ferramentas de YAML por aí, e correto: uma chave duplicada significa que um dos dois ajustes foi ignorado desde o dia em que foi acrescentado.

Comentário não para nada e também não sobrevive. Os dois formatos suportam comentário e nenhum dos seus atravessa, então o XML que você entrega carrega o dado e nenhum do raciocínio por trás. Mantenha o YAML como a fonte da verdade, gere o XML como um artefato, e nunca edite o XML diretamente — esse é o arranjo de trabalho para o qual esta conversão foi feita.