Converter TOML para JSON

TOML é o padrão de empacotamento Python e Rust há anos, e as ferramentas em volta de um repositório muitas vezes não acompanharam. Um passo de CI com jq disponível e nada mais, um script Node que precisa ler a versão de um Cargo.toml, um painel contando dependências em duzentos repositórios — todos leem JSON e nenhum lê TOML sem uma dependência nova.

É esse o caso que esta conversão serve, e funciona de forma limpa porque os dois modelos de dado se sobrepõem quase por completo. TOML é uma tabela de pares chave-valor com aninhamento e arrays — o que é um objeto JSON com aninhamento e arrays.

Um cabeçalho entre colchetes vira um objeto aninhado, e um cabeçalho pontuado vira aninhamento em vários níveis — um cabeçalho escrito para uma ferramenta e depois um linter embaixo dele produz um objeto dentro de outro, então o caminho JSON bate exatamente com o cabeçalho.

Um cabeçalho de colchete duplo é o array de tabelas, e vira um array JSON de objetos com uma entrada por ocorrência. É o que guarda os autores de um pacote Python, os binários de um crate Rust e os alvos de um build.

TOML é o único formato desta família com tipos temporais de verdade: data-hora com fuso, data-hora local, data local e hora local estão na especificação, e um leitor devolve tudo isso como data. JSON não tem tipo de data algum, então cada um vira string.

Os valores sobrevivem com uma ressalva: uma data-hora com fuso mantém o próprio fuso em vez de ser normalizada para UTC. Uma hora local ganha um componente de milissegundo que não tinha — uma hora escrita como oito da manhã chega com uma parte fracionária anexada.

TOML 1.0 exige que a implementação lide com inteiros de 64 bits assinados. Números JSON são doubles IEEE e são exatos só até cerca de nove quatrilhões. Um arquivo TOML com um inteiro acima dessa faixa é totalmente legal, e o leitor aqui para com um erro dizendo que o inteiro não pode ser representado sem perda em vez de produzir JSON com um número errado.

Recusar é a decisão certa: um identificador arredondado em silêncio é um bug que aparece semanas depois numa junção que não bate com nada. Se seu TOML tem um valor desse tamanho, coloque-o entre aspas como string na origem.

Floats TOML incluem inf e nan como valores literais. JSON não tem nenhum dos dois, e o serializador escreve null para ambos. Isso é comportamento padrão do JavaScript e é lossy de um jeito que nada avisa — um limite superior configurado como infinito e um limite não definido viram a mesma coisa no JSON.

A perda mais sutil é de tipo. TOML distingue um inteiro de um float, então 1 e 1.0 são valores diferentes com tipos diferentes. JSON tem um tipo de número só, e 1.0 é serializado como 1.

Tabelas e chaves saem na ordem em que o TOML as declarou, mantendo um arquivo convertido legível. A exceção são chaves numéricas: uma chave TOML entre aspas que é um número é reordenada antes de qualquer outra chave no seu objeto e ordenada crescente, porque é assim que objetos JavaScript ordenam chaves com cara de inteiro.

A saída é JSON comum, então jq lê sem nenhuma flag: puxar uma versão de projeto, listar nomes de dependência ou checar se uma seção de ferramenta existe são expressões de uma linha só. Costuma ser o motivo inteiro da viagem, e transforma um script de shell que ia fazer grep num TOML num que consulta de verdade.

Isso também abre validação. JSON Schema é maduro e amplamente implementado, e TOML não tem linguagem de esquema própria na especificação, então converter e depois validar é um jeito genuíno de aplicar regras internas em muitos repositórios.

TOML suporta comentário e usa bastante: o motivo de uma dependência estar fixada, o número do chamado ao lado de uma solução alternativa. JSON não tem sintaxe de comentário sob a RFC 8259, então nada disso chega.

Isso resolve a direção da relação. O TOML é o arquivo que as pessoas editam e revisam, e o JSON é gerado dele sempre que algo precisa lê-lo. Comitar o JSON junto com o TOML cria duas versões da verdade que vão divergir; gerá-lo no passo de build não.

Se a leitura acontece dentro de uma aplicação em vez de num passo de build, use um leitor de verdade. Toda linguagem grande tem um — Python tem tomllib na biblioteca padrão há várias versões, e Rust, Go e JavaScript têm opções bem mantidas. Ler o arquivo diretamente mantém os tipos temporais e a distinção inteiro-float que esta conversão achata.

O conversor ganha seu lugar na fronteira: uma inspeção pontual, um passo de CI onde adicionar uma dependência não vale a pena, ou um pipeline cuja próxima etapa só fala JSON. Tudo roda no seu navegador, então uma configuração privada com credencial dentro é segura de soltar aqui.