Converter TOML para XML

A versão interessante desta conversão não é uma migração de configuração. É um passo de relatório ou envio: os fatos sobre um projeto vivem num manifesto TOML porque foi nisso que Cargo, pip, Hugo e boa parte das ferramentas modernas se padronizaram, e o sistema que quer esses fatos — um registro de licença, um portal de fornecedor, um importador de conformidade interno, um XSLT que produz um PDF — lê XML desde 2004 e não vai mudar.

Esse enquadramento decide como ler o resto desta página. Você não está buscando uma representação fiel de TOML em XML, porque ninguém do outro lado se importa com TOML. Você está buscando o quanto a saída chega perto de uma forma de documento que outra pessoa definiu, e quais lacunas você precisa fechar à mão.

XML precisa de exatamente uma raiz, e um documento TOML é uma tabela com qualquer número de chaves, então uma regra é aplicada. Se o arquivo tem exatamente uma chave de nível superior e ela guarda uma tabela, a chave vira o elemento raiz: um arquivo contendo só uma seção `[tool]` e suas subtabelas converte para um documento `<tool>`. Se há várias chaves de nível superior — o caso comum para um manifesto com `[package]` e `[dependencies]` — tudo é embrulhado num `<root>` genérico.

Renomear essa raiz é quase sempre a primeira edição. Se a conversão vai se repetir, o movimento mais organizado é remodelar o TOML: aninhe o manifesto inteiro sob uma tabela nomeada como o schema pede, e o conversor vai produzir a raiz certa toda vez, sem um passo de pós-processamento.

Um bloco `[[bin]]` repetido três vezes é o jeito do TOML de escrever uma lista de registros, e converte para três elementos irmãos `<bin>`, cada um carregando os próprios filhos. É exatamente como o XML representa uma lista, sem elemento de invólucro e sem atributo de índice, e é o único lugar desta conversão onde nada precisa ser decidido.

Um array simples de escalares se comporta do mesmo jeito: `tags = ["a", "b"]` vira dois elementos `<tags>` com conteúdo de texto em vez de um elemento contendo uma string separada por vírgula. Se o schema receptor quer isso ou quer um `<tags>` de invólucro em torno de filhos `<tag>` é o tipo de coisa que um XSD te diz de imediato.

O TOML é incomum por ter quatro tipos temporais em vez de um, e a conversão os mantém separados em vez de colapsar num único instante UTC. Converter `launch = 2026-03-01T08:00:00Z`, `opens = 2026-03-01T08:00:00+02:00`, `seen = 2026-03-01T08:00:00`, `day = 2026-03-01` e `at = 08:00:00` produz, nessa ordem, `<launch>2026-03-01T08:00:00.000Z</launch>`, `<opens>2026-03-01T08:00:00.000+02:00</opens>`, `<seen>2026-03-01T08:00:00.000</seen>`, `<day>2026-03-01</day>` e `<at>08:00:00.000</at>`.

É o mapeamento para trabalhar ao escrever ou ler o schema: os três primeiros são `xs:dateTime` lexicamente válidos, o quarto é `xs:date`, o quinto é `xs:time`. A única coisa que todo valor ganha é um componente de milissegundo que não tinha no manifesto — `08:00:00` vira `08:00:00.000`. Isso não afeta a validação, mas qualquer coisa comparando o texto contra um literal escrito da forma curta não vai bater.

O deslocamento é carregado exatamente como escrito em vez de normalizado: `2026-03-01T08:00:00+02:00` chega como `2026-03-01T08:00:00.000+02:00`, não como `06:00:00.000Z`. É o comportamento melhor para um documento que alguém vai ler, e significa que dois elementos guardando o mesmo instante podem guardar textos diferentes.

Os valores sem fuso são os que valem pensar antes de enviar. Um datetime local do TOML diz que o relógio de parede marcava oito da manhã em algum lugar, e o XML repete isso sem dizer onde. O horário local é a surpresa mais aguda: `at = 08:00:00` não tem data nenhuma, então um elemento que o schema declarou como `xs:dateTime` rejeita ele.

O TOML deixa uma chave ser quase qualquer coisa se estiver entre aspas: `"2024 report"`, `"line-length"`, `"x:y"`. Nomes de elemento XML não podem começar com dígito e não podem conter espaço ou, sem um namespace declarado, dois-pontos. O gravador reescreve em vez de recusar: qualquer coisa fora de letras, dígitos, sublinhado, hífen e ponto vira um sublinhado.

Então `"2024 report"` vira `<_2024_report>`, `"a b"` vira `<a_b>` e `"x:y"` vira `<x_y>`. Esse último é o que vale observar: uma chave escrita com dois-pontos porque alguém pensava num prefixo de namespace perde os dois-pontos e vira um nome comum, o que não é o que o schema espera. Hífens e pontos sobrevivem intactos.

Por padrão toda chave TOML vira um elemento filho, e a maioria dos schemas quer pelo menos alguns valores como atributos em vez disso. A convenção que o gravador segue é um arroba na frente do nome da chave: dentro de uma tabela, `"@id" = 42` produz `id="42"` naquele elemento em vez de um filho `<id>`. O TOML permite a chave porque está entre aspas.

Texto de elemento ao lado de atributos usa a chave `"#text"` do mesmo jeito. As duas valem conhecer porque transformam um trabalho de duas passagens num só — remodelar o TOML com alguns arrobas é mais rápido e repetível do que converter e depois mover valores para atributos com um XSLT.

Nenhuma declaração XML é escrita, então o documento começa no elemento raiz. Nenhum namespace é declarado, nenhum local de schema é referenciado. A saída é indentada em dois espaços por nível e termina com uma quebra de linha. Texto e valores de atributo são escapados para `&`, `<`, `>` e `"`.

Um array TOML vazio é outro caso silencioso: `tags = []` não produz elemento nenhum, só uma linha em branco onde um teria ido. Isso é defensável — não há membro para repetir — e ainda assim vai surpreender um schema que declara o elemento com `minOccurs="1"`.

Os dois formatos suportam comentários, e nem o leitor nem o gravador os carregam adiante, então toda linha com `#` explicando por que uma dependência está fixada ou por que um ajuste tem um valor incomum está ausente do XML. Não é uma perda pequena num manifesto, onde os comentários frequentemente são o único registro de uma decisão.

Trate o XML como um artefato gerado, não como uma cópia. Regenere sempre que o manifesto mudar em vez de editá-lo e torcer para os dois ficarem sincronizados, e mantenha fora do repositório a menos que o processo de envio exija uma cópia versionada.

Tudo acima é um motivo para a primeira tentativa não validar: a raiz vai ter o nome errado, um horário local não vai satisfazer um elemento declarado `xs:dateTime`, alguns valores vão ser filhos onde o schema quer atributos, e uma lista opcional pode faltar por completo. Encontrar tudo isso numa passagem é bem mais rápido que encontrar em quatro e-mails de rejeição.

`xmllint --schema contract.xsd out.xml --noout` dá a lista completa de reclamações com números de linha, e está disponível em quase toda máquina. Resolva reformulando o TOML em vez de editando o XML, para a próxima passagem começar de um lugar melhor.