JSON vs YAML

Sintaxe: pontuação versus indentação

A gramática do JSON usa seis caracteres estruturais — colchetes, chaves, dois-pontos e vírgula — então o aninhamento de um documento fica visível na sua pontuação e um linter pode apontar o caractere exato que está errado. O YAML gasta seu orçamento de pontuação com legibilidade: aninhamento é indentação, listas são travessões, e pares chave/valor não precisam de separador além de dois-pontos e um espaço. O resultado é que um documento JSON de cinco linhas vira duas linhas de YAML, e um profundamente aninhado fica drasticamente mais curto — ao preço de uma classe inteira de erro que o JSON não tem: a falha do número errado de espaços, que alguns parsers reportam em uma linha distante do seu erro.

Tipos: estrito versus inferido

Todo valor JSON se declara: strings usam aspas, números ficam nus, booleanos são exatamente true e false. O YAML infere. Um yes, no, on, off, true ou false sem aspas é um booleano; um 2026-09-19 sem aspas é uma data; e um valor como 1.20 pode virar silenciosamente o número 1.2 dependendo do leitor. A falha tem nome na comunidade — o problema da Noruega, por causa de códigos de país como NO que viram o booleano false — e é o argumento mais forte a favor de usar aspas defensivamente no YAML, mesmo quando o parser não exige.

O outro lado é deliberado: o YAML quer arquivos de configuração em que 8080 é lido como número de porta sem cerimônia. O JSON quer intercâmbio, onde emissor e consumidor precisam concordar em cada byte, e inferência é um bug. Cada formato otimiza para o leitor que espera.

Tamanho, desempenho e ferramentas

O YAML costuma ser o arquivo mais curto e o parse mais lento: escanear indentação, escalares em bloco multilinha e resolver âncoras custam mais do que a gramática de passagem única do JSON. Para configuração lida uma vez na inicialização, isso é irrelevante; para um formato que cruza a rede milhões de vezes por dia, é exatamente por isso que o YAML nunca desalojou o JSON. As ferramentas são a outra assimetria — toda linguagem traz um parser JSON na biblioteca padrão, enquanto parsers de YAML são de terceiros, com diferenças reais no que aceitam, razão pela qual este conversor documenta o subconjunto suportado em vez de prometer a spec completa.

• Tamanho do payload: o YAML vence em arquivos escritos à mão; o JSON com minificação costuma vencer na transmissão, porque suas regras de aspas comprimem de forma previsível.
• Mensagens de erro: parsers JSON apontam o caractere problemático; parsers YAML apontam a linha em que a indentação deixou de bater.
• Interoperabilidade: JSON é o padrão em todo lugar — pipelines de logs, APIs HTTP, armazenamento do navegador. YAML é o padrão em Kubernetes, pipelines de CI e Ansible.
• Ida e volta: JSON→YAML→JSON é sem perdas com um par compatível. YAML→JSON pode ter perdas no instante em que o arquivo usou recursos que o JSON não tem — âncoras, múltiplos documentos ou chaves que não são string.

Quando escolher cada um

A decisão raramente é sobre preferência e normalmente sobre o leitor. Escolha JSON quando um programa produz o documento e outro programa o consome: payloads de API, logs estruturados, estado armazenado, qualquer coisa que cruze um limite de confiança. Escolha YAML quando uma pessoa escreve e mantém o documento: pipelines de CI, manifests do Kubernetes, arquivos docker-compose, qualquer configuração em que quem revisa precise ler um diff e entendê-lo sem decifrar pontuação.

E a orientação se inverte com clareza: se você se pegar formatando JSON à mão com quinze níveis de aninhamento, esse arquivo provavelmente quer ser YAML. Se você se vê fazendo parse de YAML em tempo de execução dentro de um serviço, esse arquivo provavelmente quer ser JSON. Os conversores linkados abaixo tornam a travessia um passo de um clique, não um projeto de migração.