Comparação de Configurações JSON/YAML/TOML: Guia de Seleção para Desenvolvedores

Originário do JavaScript, o JSON foi projetado como um formato leve de intercâmbio de dados multiplataforma. Suas regras de sintaxe são baseadas no padrão ECMAScript, e ele prioriza a confiabilidade para a análise por máquina. A RFC 8259 define explicitamente seu propósito principal como a transmissão entre sistemas de dados estruturados.

O YAML, cujo nome completo é YAML Ain't Markup Language, é posicionado como dados de configuração legíveis por humanos. Ele prioriza a redução da barreira para edição manual, simplifica a escrita hierárquica através de uma estrutura baseada em indentação, e é adequado para cenários onde pessoal não técnico precisa editar configurações.

O TOML, cujo nome completo é Tom's Obvious, Minimal Language, foi projetado como um formato de configuração com semântica clara. Ele defende que a semântica da configuração deve ser analisada sem ambiguidade, e evita interpretações ambíguas através de seccionamento explícito e estrutura de chave-valor.

As diferenças nos recursos comuns entre os três formatos afetam diretamente a experiência de escrita de configurações. O JSON não reserva espaço para comentários, e a maioria dos analisadores não suporta sintaxe de comentários. Tanto o YAML quanto o TOML suportam nativamente comentários de linha única e multi-linha, tornando conveniente escrever descrições de configuração.

As diferenças em strings multi-linha e tipos de data correspondem aos requisitos de diferentes cenários: o YAML é adequado para escrever descrições multi-linha ou conteúdo de modelo, enquanto o JSON requer processamento de escape para quebras de linha, o que tem compatibilidade consistente, mas é complicado de escrever.

O problema mais conhecido do JSON é a falta de suporte oficial a comentários. Se alguns desenvolvedores adicionarem comentários ao JSON, a mudança para um analisador padrão irá disparar diretamente uma falha de análise, fazendo com que a configuração não possa ser carregada. Algumas soluções derivadas como JSONC adicionam suporte a comentários, mas não foram incorporadas ao padrão oficial.

O YAML tem o conhecido problema da Noruega: quando uma string está no formato 20:03, alguns analisadores irão convertê-la automaticamente para um tipo de tempo Base60, resultando no valor 1203, que não corresponde ao valor de string esperado. Este problema se origina das regras de conversão implícita de tipos do YAML.

O TOML não tem conversão implícita de tipos. Todos os tipos de valor são marcados explicitamente pela sintaxe, e nenhum tipo é inferido automaticamente. Portanto, ele não tem problemas de ambiguidade semelhantes, e o resultado do tipo corresponde à expectativa de quem escreve.

Existe uma分层 clara no nível de adoção dos três formatos em diferentes pilhas de tecnologia. A tabela a seguir resume o status popular de cada formato por cenário de aplicação, bem como a maturidade dos analisadores no ecossistema correspondente.

Ao converter entre diferentes formatos, existem limites fixos para perda de informação. A ferramenta de conversão de formato OKfmt retém informações válidas com base no suporte de sintaxe, e descarta conteúdo incompatível. Ao converter JSON para YAML ou TOML, nenhuma informação nativa é perdida, e todas as estruturas podem ser mapeadas completamente.

Ao converter YAML para JSON, as informações de comentários e tipo de data nativa do YAML serão perdidas, pois o JSON não suporta esses dois recursos. Ao converter TOML para JSON, apenas comentários são perdidos, e todos os tipos de estrutura podem ser mapeados completamente. Ao converter YAML para TOML, tipos de data nativos serão convertidos para strings no formato correspondente, e comentários podem ser retidos completamente.