JSON vs YAML vs XML: quando usar cada um de verdade

JSON, YAML e XML são todos capazes de representar essencialmente os mesmos dados subjacentes — objetos aninhados, listas, pares chave-valor, valores simples — o que é exatamente o motivo pelo qual a escolha entre eles tantas vezes se resume ao hábito ou ao que um framework usa por padrão, em vez de uma decisão pensada. Mas os três foram projetados em épocas diferentes para casos de uso principais diferentes, e esses objetivos de design originais ainda aparecem hoje como diferenças práticas reais: qual é agradável de editar manualmente, qual uma máquina consegue validar rigorosamente, qual se aninha profundamente sem ficar ilegível, e qual já tem todo um ecossistema de ferramentas que o espera. Escolher com base nessas diferenças, em vez de no hábito, é o que de fato torna uma escolha de formato boa em vez de meramente convencional.

O JSON foi extraído diretamente da sintaxe de objetos literais do JavaScript, e essa origem é precisamente o motivo de ele ter se tornado o formato padrão de troca de dados para APIs web: qualquer ambiente JavaScript consegue analisá-lo nativamente sem nenhuma biblioteca, sua gramática é pequena o suficiente para ser implementada corretamente em uma tarde em praticamente qualquer outra linguagem, e suas regras rígidas — sem comentários, sem vírgulas sobrando, chaves só entre aspas duplas — significam que um analisador de JSON tem muito pouca ambiguidade para resolver, o que torna o JSON rápido de analisar e fácil de gerar corretamente. Essa mesma rigidez é a principal fraqueza do JSON para qualquer coisa que uma pessoa precise editar diretamente à mão: a ausência de comentários significa que não há como deixar uma nota explicativa em um arquivo de configuração, e a sintaxe de chaves aninhadas carregada de pontuação fica genuinamente difícil de acompanhar visualmente assim que uma estrutura passa de três ou quatro níveis de profundidade.

É por isso que o JSON domina a comunicação entre máquinas — respostas de API, troca de dados entre serviços, qualquer coisa gerada e consumida principalmente por código em vez de lida e editada por uma pessoa — enquanto continua sendo uma escolha um tanto desajeitada para arquivos de configuração que um humano precisa manter manualmente.

O YAML foi projetado com a prioridade oposta: legibilidade humana e facilidade de edição manual, ao custo de uma especificação de análise consideravelmente mais complexa do que a do JSON. Ele usa indentação em vez de chaves para representar o aninhamento, suporta comentários de verdade com `#`, e permite strings sem aspas no caso comum, tudo o que faz um arquivo YAML bem formatado parecer quase anotações estruturadas em texto simples em vez de código — que é exatamente o motivo pelo qual o YAML se tornou o padrão para arquivos de configuração em uma enorme fatia das ferramentas de desenvolvimento: definições de pipeline de CI/CD, manifestos de orquestração de contêineres, configuração de aplicações que um humano realmente precisa ler e modificar diretamente. A contrapartida é que a dependência do YAML em espaços em branco para a estrutura o torna genuinamente frágil para editar corretamente à mão — uma indentação mal colocada muda silenciosamente a qual bloco algo pertence, em vez de lançar um erro óbvio — e sua especificação mais permissiva e cheia de recursos produziu, ao longo dos anos, inconsistências reais e documentadas de análise entre diferentes bibliotecas de YAML, uma ambiguidade para a qual a gramática muito mais rígida do JSON simplesmente não deixa espaço.

O XML é anterior tanto ao JSON quanto ao YAML e foi projetado com uma prioridade diferente de novo: estrutura de documento rígida e verificável, com um ecossistema maduro de padrões ao redor — linguagens de esquema que conseguem validar a estrutura de um documento antes mesmo de o código da aplicação tocá-lo, XPath para consultar dentro de um documento, namespaces para combinar vocabulários de fontes diferentes sem colisões de nomes. Essa profundidade de ferramentas continua genuinamente sem paralelo no JSON ou no YAML em contextos empresariais e centrados em documentos: setores com requisitos rígidos de troca de dados, formatos de documento padronizados e sistemas legados de vida longa construídos ao seu redor ainda dependem do XML precisamente por causa dessa maturidade de validação e ferramentas, não por pura inércia. A contrapartida bem conhecida é a verbosidade — representar os mesmos dados aninhados em XML normalmente exige visivelmente mais caracteres do que o JSON equivalente, já que cada valor precisa de uma tag de abertura e outra de fechamento em vez de um único caractere de pontuação — que é o principal motivo pelo qual o XML perdeu o papel de formato padrão para APIs para o JSON à medida que os serviços web amadureceram e o tamanho do payload e a simplicidade de análise se tornaram prioridades maiores do que a validação no estilo documento.

Para o corpo de uma requisição ou resposta de API, o JSON é quase sempre a escolha padrão certa hoje em dia — é o que a maioria das bibliotecas cliente, a maioria das ferramentas de documentação, e a maioria dos desenvolvedores do outro lado de uma integração vai esperar sem nenhum atrito. Para um arquivo de configuração que uma pessoa vai ler e editar manualmente com regularidade — pipelines de CI, configuração de aplicações, definições de infraestrutura como código — os comentários e o aninhamento mais limpo do YAML realmente valem a pena, desde que as ferramentas ao redor validem a sintaxe com cuidado, já que é aí que a fragilidade do YAML com espaços em branco mais incomoda. Para um formato centrado em documentos com uma necessidade real de validação rígida de esquema, namespaces para combinar vocabulários, ou integração com um sistema empresarial já existente baseado em XML, a verbosidade do XML é um preço razoável por uma maturidade de ferramentas que nenhum dos outros dois replica totalmente. A escolha de formato que realmente serve bem a um projeto é a que combina com quem — ou o quê — vai ler e escrever o arquivo com mais frequência, não a que por acaso é o padrão mais na moda do momento.