Converter XML para YAML

O XML gasta mais ou menos metade dos caracteres dizendo onde um elemento termina. O YAML diz isso com indentação, então o mesmo documento sai bem mais curto, e cada nível de aninhamento é um passo visual em vez de um par a procurar para casar. Num pom do Maven ou num web.config, essa é a diferença entre rolar a tela e ler.

A estrutura fica igual. Todo elemento vira uma chave, os filhos viram o mapeamento abaixo dela, e o texto vira o valor. Nada é reordenado e nada é resumido, então o que você está olhando é o mesmo documento com a pontuação removida — exatamente o que se quer quando o objetivo é entender o que o arquivo diz.

Atributo atravessa como chave prefixada com @, e um elemento que carrega atributo e texto guarda esse texto sob a chave #text. Os dois vêm entre aspas, porque o YAML trata @ como um indicador reservado no início de um escalar simples e # como o início de um comentário.

Parece ruído e é correção. Se você editar o arquivo à mão, mantenha essas aspas: removê-las produz um YAML que ou não analisa ou, no caso de #text, silenciosamente transforma o resto da linha num comentário e perde o valor. O mesmo vale se você digitar uma chave de novo enquanto remodela a saída num arquivo de valores.

Este é o motivo mais forte para fazer a conversão. Comparar XML é infeliz porque uma mudança um nível abaixo aparece como várias linhas de tag, e reformatação por uma ferramenta reescreve o arquivo inteiro. Converter as duas versões e comparar o YAML mostra os valores mudados nas próprias linhas, com o caminho da chave visível acima deles.

Uma ressalva faz toda a diferença. Como um único elemento repetido vira um mapeamento e dois viram uma lista, uma versão que acrescentou uma segunda dependência muda a forma daquele galho e não só o conteúdo, então a comparação mostra o bloco inteiro como reescrito. Isso não é o conversor perdendo informação — é a forma de fato mudando — mas saber disso de antemão evita ler uma diferença grande como uma mudança grande.

Prefixo é preservado como parte do nome da chave, então um documento usando soap: ou xsi: produz chaves contendo dois pontos. O gerador emite essas chaves sem aspas, e elas leem corretamente pelo mesmo analisador. As próprias declarações de espaço de nome sobrevivem como atributo, então um xmlns padrão chega como uma chave "@xmlns" entre aspas na raiz.

Dois pontos dentro de uma chave sem aspas é o tipo de coisa que vale apertar à mão antes de o arquivo viajar. Se o YAML vai ser lido por outra ferramenta, coloque aspas nessas chaves você mesmo — não custa nada e remove uma classe de problema que só aparece no ponto em que outra pessoa analisa o arquivo. Nada resolve prefixo para a URI de espaço de nome dele, então dois documentos usando prefixos diferentes para o mesmo espaço de nome produzem YAML que não compara limpo entre si.

Valores que se leem como número são analisados, tanto em texto de elemento quanto em atributo. Uma versão do Maven como 4.13.2 continua string, porque tem dois pontos e não pode ser um número, e o mesmo vale para um endereço ou um caminho. Um atributo de versão escrito 1.0 vira 1, e um valor com zero à esquerda escrito 007 vira 7.

Numa configuração que é lida em vez de executada, o dano se limita a como o valor parece, e ainda assim importa: uma versão de esquema renderizada como 1 em vez de 1.0 numa revisão é um valor que alguém vai questionar ou, pior, copiar. Escaneie os valores de aparência numérica na saída uma vez. Se o YAML vai para qualquer lugar além de um olho humano, coloque aspas nos que eram pensados como identificador.

Um valor contendo quebra de linha é escrito como um escalar de bloco — um caractere de barra vertical com o texto indentado abaixo — o que mantém legível em vez de escapar tudo numa linha só. Um valor longo de linha única é escrito como está, sem quebra. Os dois são as escolhas certas para um arquivo pensado para ser lido.

Um elemento vazio ou autofechado vira uma string vazia, escrita como um par de aspas. O XML não distingue um elemento vazio de um contendo nada, então nenhuma informação se perde, mas uma string vazia é visualmente fácil de passar batido num arquivo longo — se você está auditando uma configuração atrás de valor não definido, procure pelas aspas vazias em vez de confiar no olho.

O XML aceita comentário, o YAML aceita comentário, e nenhum dos seus sobrevive. O analisador descarta e nada escreve de volta. Numa carga de dados isso é irrelevante; num arquivo de build é a maior perda isolada, porque o comentário acima de uma versão de dependência fixada costuma ser o único registro sobrevivente de por que ela foi fixada.

O arranjo de trabalho que evita a armadilha é tratar o YAML como uma cópia de leitura e manter o XML como a origem. Se o YAML em vez disso vai virar a origem — uma migração de verdade para o Ansible ou um chart do Helm — programe a passagem que copia os comentários como parte do trabalho, antes de o XML ser apagado e o raciocínio ir junto.

Uma configuração convertida ainda não é um arquivo de valores nem um conjunto de variáveis. Ela carrega artefato de XML — as chaves @, as chaves #text, uma declaração de espaço de nome na raiz, e possivelmente uma chave ?xml da linha de declaração — que não significa nada para o que você está alimentando. Apagar isso é a primeira passagem.

A segunda é nomear. Nome de elemento XML costuma ser verboso de um jeito que fazia sentido com um esquema por trás, e uma configuração YAML normalmente quer nomes mais curtos e mais planos. As duas passagens são manuais e são a migração de verdade; a conversão só entrega um ponto de partida legível em vez de uma parede de tags.

Converta quando o objetivo é entender, revisar ou comparar: o YAML é mais curto, a estrutura é óbvia, e tudo roda no seu navegador no tempo que leva para soltar o arquivo. É um bom hábito para qualquer arquivo de configuração que te entregaram e sobre o qual você precisa raciocinar antes de mudar.

Não converta quando o arquivo é validado por um esquema, assinado, ou consumido por uma ferramenta que lê XML. O XML é o artefato nesse caso, e uma cópia YAML é uma segunda versão da verdade que vai se desviar da primeira. Leia como YAML, mude como XML.