Converter JSON para TOML

JSON não tem comentário. Isso está na especificação, não é descuido, e é o motivo principal de configuração escrita em JSON ser desagradável de manter: o porquê de um timeout ser 45 segundos não pode morar ao lado do 45. TOML, que levou anos de versões 0.x até chegar à 1.0 em janeiro de 2021 e hoje é o formato de configuração do Cargo, do pyproject.toml e do Hugo, tem comentário — geralmente essa é a motivação inteira desta conversão.

O segundo motivo é a planificação. Uma configuração JSON com três níveis de profundidade é três níveis de chaves e muita indentação; a mesma coisa em TOML é uma linha de cabeçalho tipo [server.tls.client] e uma lista curta de chaves embaixo. Nada nos dados muda, mas o diff que um revisor vê quando um valor muda vira uma linha em vez de um bloco reindentado.

Um documento TOML é uma tabela. Ele não pode começar com um array do jeito que um documento JSON pode, então um arquivo cujo primeiro caractere é um colchete não tem onde mapear. A conversão lida com isso em vez de falhar: um valor que não é objeto é embrulhado numa chave chamada items, e a saída começa com [[items]].

Isso mantém o arquivo válido, e é um espaço reservado, não uma resposta definitiva: nenhum conversor sabe se a ferramenta que vai ler o arquivo espera que essa lista se chame dependencies, servers ou plugins. Renomeie a chave na primeira linha e o resto do arquivo já está correto.

Este é o ponto que vale conferir sempre. TOML não tem literal de nulo, e o gravador não inventa um: uma chave cujo valor JSON era null simplesmente não é escrita. Converta {"a": null} e a saída é um arquivo vazio. Converta uma tabela com uma chave real e uma chave nula, e só a chave real aparece.

Se isso importa depende inteiramente da ferramenta que vai ler o resultado. Muitos leitores de configuração tratam uma chave ausente e uma chave nula do mesmo jeito. Outros distinguem, e ali a conversão mudou a configuração em silêncio. A defesa é buscar null no JSON antes de converter, em vez de comparar os dois arquivos depois.

Isso costuma surpreender quem espera que TOML seja um formato mais fraco que JSON. Uma lista de registros é expressa pelo mesmo cabeçalho de tabela repetido: [[servers]] três vezes dá três servidores, cada um com suas próprias chaves embaixo. É mais verboso que um array JSON e bem mais fácil de editar, porque adicionar um quarto servidor significa copiar cinco linhas em vez de balancear colchetes.

Os membros não precisam ser iguais. Um array em que o primeiro objeto tem id e name e o segundo acrescenta region converte sem reclamar, e o TOML continua válido — cada bloco carrega as chaves que tem. É uma vantagem real sobre os alvos tabulares deste site, onde um array heterogêneo precisa ser reconciliado em um único conjunto de colunas.

Um cabeçalho de tabela TOML é dono de tudo que vem escrito abaixo até o próximo cabeçalho. Isso significa que uma chave simples colocada depois de [server] pertenceria a server, fosse qual fosse a intenção do autor. Então o gravador eleva todo valor de topo antes do primeiro cabeçalho de tabela.

A saída, portanto, não segue a ordem do seu JSON, e não poderia seguir: essa é a única reordenação que preserva o significado, e qualquer outra mudaria a qual tabela uma chave pertence. Se o agrupamento original importava para a leitura, restaure-o movendo blocos de tabela inteiros — isso é seguro — em vez de mover chaves individuais.

Quatro níveis de aninhamento JSON viram uma única linha de cabeçalho: {"a":{"b":{"c":{"d":1}}}} converte para [a.b.c] com d = 1 embaixo. TOML expressa profundidade no cabeçalho em vez de na indentação, o que explica por que uma configuração profundamente estruturada costuma ficar mais curta e mais plana em TOML.

Isso também tem um limite de gosto, não de validade: um cabeçalho como [build.targets.linux.arm64.flags] é legal e ninguém gosta de ler. Se o arquivo convertido tiver cabeçalhos além de três ou quatro segmentos, geralmente é sinal de que a configuração merece ser dividida em arquivos ou ferramentas separadas.

A saída não tem comentário nenhum, porque a entrada não tinha onde guardar um. JSON não carrega comentários, então não há nada para traduzir — isso não é uma falha do conversor, é o motivo pelo qual valeu a pena deixar o JSON de lado.

O que torna os primeiros cinco minutos depois de converter a parte mais valiosa do exercício: o arquivo TOML é a versão desta configuração capaz de guardar o conhecimento institucional sobre ela — quais valores são seguros de mudar, qual precisa bater com um valor em outro repositório. Escrever isso agora custa zero.

TOML tem quatro tipos de data e hora, incluindo uma data-hora com fuso que é um valor de primeira classe, não uma string. JSON não tem nenhum: todo timestamp em todo arquivo JSON do mundo é uma string por convenção.

Então um valor JSON como "2024-01-01T00:00:00Z" é escrito como string TOML entre aspas, o que é correto e não é o que o formato poderia expressar. Se a ferramenta que vai ler o arquivo quer uma data-hora de verdade, remova as aspas à mão nessas linhas.

A checagem mais barata é uma ida e volta: converta o TOML de volta para JSON e compare com o que você começou. Chaves que tinham null vão estar ausentes, e nada mais deveria diferir.

A segunda checagem é a própria ferramenta. Cargo, Hugo e a maioria dos empacotadores Python avisam na hora se o documento não faz sentido para eles, e isso pega o que a ida e volta não pega: um arquivo corretamente convertido cuja chave de topo ainda se chama items porque ninguém a renomeou.

Nesta aba do navegador, no seu próprio processador. As duas metades são JavaScript — o leitor JSON é o que já vem no navegador, e o gravador TOML é uma biblioteca pequena carregada sob demanda — então nenhuma requisição carrega o arquivo para lugar nenhum, sem conta, sem fila.

Isso importa mais para configuração do que para a maioria dos dados. Um arquivo de configuração JSON é exatamente o tipo de coisa que guarda hostname interno, nome de bucket, conta de serviço e às vezes uma credencial que alguém esqueceu de remover, e enviá-lo a um conversor web seria a parte realmente contrária à política. Aqui não há nada para enviar.