YAML vs JSON — quando usar qual, e por que a maioria das equipes usa ambos

Se você já abriu um manifesto de Kubernetes, um workflow de GitHub Actions ou um arquivo docker-compose, você usou YAML. Se você já chamou uma REST API ou escreveu um arquivo de configuração para um projeto Node.js, você usou JSON. Ambos são formatos de serialização. Ambos descrevem os mesmos tipos de estruturas de dados — maps, arrays, strings, números, booleanos, null. Então por que temos dois?

A resposta curta: YAML otimiza para humanos, JSON otimiza para máquinas. A resposta longa envolve algumas décadas de experiência de desenvolvimento, algumas reuniões de comissão e uma quantidade surpreendente de edge cases. Vamos percorrer.

O que JSON faz bem

JSON (JavaScript Object Notation) se popularizou no início dos anos 2000 como formato de payload para requisições AJAX. Era deliberadamente pequeno — seis tipos de valor, sem comentários, sem vírgulas finais, sem ambiguidade. Essa rigidez é sua superpotência na transmissão:

• Parsers são pequenos e rápidos. JSON.parse vem com cada navegador e cada runtime de linguagem. Não há nada para pensar.
• Erros são inequívocos. Quando JSON está quebrado, o parser diz exatamente qual linha e coluna.
• Máquinas concordam na semântica. Um número é um número, uma string é uma string, true é true. Não existe o debate “é yes um booleano ou uma string?”

É por que JSON é a língua franca de APIs. Quando dois serviços estão se comunicando, você quer o formato com menos surpresas.

O que YAML faz bem

YAML (YAML Ain’t Markup Language) foi projetado para arquivos de configuração escritos por humanos. Ele trocou parte da rigidez de JSON por legibilidade:

• Sem chaves colchetes, sem colchetes. Estrutura é indentação. Um docker-compose.yml é lido de cima para baixo como uma lista.
• Comentários. Um # inicia um comentário. JSON não tem sintaxe de comentários — e a falta de comentários é a razão mais comum pela qual equipes migram de JSON para YAML em arquivos de configuração.
• Âncoras e referências. &anchor e *reference permitem que você defina um valor uma vez e o reutilize. JSON não tem equivalente; você tem que copiar e colar.
• Strings multilinha. Blocos literais (|) e blocos dobrados (>) lidam com texto e código sem malabarismo de escape.

É por que YAML domina em lugares onde humanos leem e escrevem à mão: Kubernetes, GitHub Actions, GitLab CI, playbooks Ansible, docker-compose, CloudFormation, especificações OpenAPI e a onda de arquivos de configuração de agentes de IA da era 2025 (.github/agents.yml, manifestos de servidores MCP, harnesses de avaliação).

A assimetria

Aqui está o segredo sujo: YAML é um superconjunto do modelo de dados de JSON. Todo arquivo JSON válido pode ser expresso como YAML, mas o inverso não é verdade. YAML tem funcionalidades que JSON simplesmente não tem — comentários, âncoras, arquivos multi-doc, tags personalizadas. Uma vez que você escreve YAML com âncoras, não pode convertê-lo de volta para JSON sem perdas. As âncoras desaparecem.

Isso importa para ferramentas. Se você tem um arquivo YAML com &defaults *defaults, converter para JSON vai ou expandir as referências (silenciosamente produzindo um arquivo maior) ou descartá-las (silenciosamente produzindo um arquivo menor). O mesmo vale para comentários. JSON não tem lugar para colocá-los.

Quando usar qual

Use JSON quando:

• Você está enviando dados pela rede (APIs, filas de mensagens, payloads de eventos).
• O arquivo é lido por código, não por humanos.
• Você quer mensagens de erro inequívocas de parsers rígidos.
• Você está otimizando para velocidade de parsing em dispositivos com restrições.

Use YAML quando:

• Um humano é o autor e leitor principal do arquivo.
• Você quer comentários para explicar a intenção.
• Você quer reutilizar pedaços de configuração com âncoras.
• As ferramentas do seu domínio esperam isso (Kubernetes, CI, etc.).

A resposta pragmática para a maioria das equipes: JSON para a transmissão, YAML para configuração, ambos para intercâmbio de dados. Em caso de dúvida, armazene a versão canônica em JSON (sem perdas) e emita YAML para consumo humano (com comentários e âncoras) apenas quando o público é um desenvolvedor abrindo um editor de texto.

Armadilhas comuns ao converter entre os dois

1. Números e booleanos são tipificados automaticamente no YAML. port: 8080 é um número. port: "8080" é uma string. Esquecer de colocar aspas pode alterar seu tipo.
2. Âncoras e comentários são descartados no JSON. Não há como contornar isso — o formato não tem lugar para colocá-los.
3. O null de YAML é ambíguo. key: (valor vazio) é null. key: null também é null. key: "" é uma string vazia. Três coisas diferentes.
4. Tabs quebram YAML. A indentação deve ser espaços. Tabs são um erro.
5. YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1 tratava yes, no, on, off como booleanos. YAML 1.2 (a especificação usada por js-yaml, PyYAML e a maioria dos parsers em 2026) não. A versão de manutenção 1.2.2 em 2025 apertou alguns edge cases em torno de marcadores de fim de documento e tratamento de BOM — a maioria dos parsers adotou as correções silenciosamente. Se você está migrando de um codebase de 2018, sua configuração pode ainda quebrar de maneiras sutis.

Ferramentas que ajudam

Quando você está alternando entre os dois — e vai alternar, porque toda equipe usa ambos — um conversor client-side rápido é seu amigo. As ferramentas YAML to JSON e JSON to YAML no DevSpeedTools rodam inteiramente no seu navegador, então arquivos de configuração com segredos nunca saem da sua máquina. Abra DevTools → Network e você verá nenhuma requisição com seus dados.

Para YAML que ficou bagunçado ao longo do tempo, o formatador de YAML normalizará a indentação para dois espaços e corrigirá aspas inconsistentes. Para arquivos que não analisam, o validador de YAML mostra a linha e coluna exata de cada erro.

A conclusão: pare de tratar YAML e JSON como formatos concorrentes. Eles são complementares. O formato certo depende de quem está lendo o arquivo — uma máquina, ou um desenvolvedor cansado às 23h tentando descobrir por que a implantação dele quebrou.