JSON vs YAML: Qual formato de configuração você deve usar?
Resposta rápida
Use JSON para APIs, intercâmbio de dados e casos em que análise e validação rigorosas são importantes. Use YAML para arquivos de configuração, manifestos de DevOps e casos em que a legibilidade humana e os comentários são importantes. YAML é um superconjunto JSON — todo documento JSON válido é YAML válido.
Introdução
JSON e YAML são formatos de serialização de dados legíveis por humanos. JSON é estrito, mínimo e onipresente na web APIs. YAML é um superconjunto de JSON que adiciona comentários, strings multilinhas, âncoras e estrutura baseada em recuo – tornando-o popular para arquivos de configuração (Docker Compose, Kubernetes, pipelines CI/CD).
Passo a passo
-
Compare sintaxe e legibilidade
JSON usa colchetes e aspas: {"key": "value"}. YAML usa recuo e dois pontos: chave: valor. YAML é mais limpo para configuração - sem necessidade de aspas para strings, sem vírgulas entre itens, sem colchetes. JSON é mais explícito e menos sujeito a erros para intercâmbio de dados.
-
Comparar recursos
YAML suporta: comentários (#), strings multilinhas (|, >), âncoras (&) e aliases (*), vários documentos em um arquivo (---) e tipos complexos. JSON não suporta nada disso - sem comentários, sem strings multilinhas, sem referências. A simplicidade de JSON é intencional: é um formato de intercâmbio de dados, não uma linguagem de configuração.
-
Compare segurança e análise
A análise de JSON é rápida e segura — JSON.parse está integrado em todos os mecanismos JavaScript. A análise de YAML é mais lenta e complexa - a especificação YAML tem mais de 80 páginas em comparação com as 2 páginas de JSON. YAML tem riscos de segurança (ataque de bilhões de risadas por meio de âncoras) que JSON não tem. Sempre use um analisador YAML seguro que desative as âncoras.
-
Compare o uso do ecossistema
JSON: REST APIs, package.json, tsconfig.json, bancos de dados NoSQL, aplicativos da web. YAML: Docker Compose, manifestos do Kubernetes, GitHub Actions, playbooks Ansible, configurações de CI/CD, especificações OpenAPI. JSON domina os dados de tempo de execução; YAML domina a configuração.
-
Decida com base no seu caso de uso
APIs, intercâmbio de dados, NoSQL, estado do aplicativo web: JSON. Arquivos de configuração, DevOps, CI/CD, infraestrutura como código: YAML. Se os humanos escreverem à mão: YAML. Se as máquinas gerarem e consumirem: JSON.
Exemplos
Mesma configuração em JSON e YAML
Entrada: JSON: {"server": {"port": 8080, "host": "localhost"}}
YAML: server:\n port: 8080\n host: localhost
Saída: YAML é 30% mais curto e suporta comentários. JSON é mais estrito e universalmente analisável.
Problemas comuns
- Erros de indentação YAML: YAML usa indentação para estrutura e um único espaço errado quebra a análise - use um editor com linting YAML e sempre use espaços, nunca tabulações.
- Ataque YAML de bilhões de risadas: âncoras e aliases YAML podem criar expansão exponencial, causando DoS - use um analisador YAML seguro que desativa âncoras (por exemplo, yaml.safe_load em Python).
- JSON não tem comentários: a especificação JSON proíbe comentários, tornando os arquivos de configuração mais difíceis de anotar - use YAML para configuração editada por humanos, JSON para dados gerados por máquina.
- Surpresas de digitação implícita do YAML: o YAML converte automaticamente sim/não em booleanos e 1.0 em flutuante, o que pode quebrar campos de string - cite strings explicitamente para evitar coerção de tipo inesperada.
Dicas
- Use YAML para configuração de autoria humana (Docker Compose, Kubernetes, CI/CD) e JSON para intercâmbio de dados gerados por máquina (APIs, NoSQL, estado do aplicativo).
- Sempre use um analisador YAML seguro que desative âncoras e aliases — nunca use um carregador YAML de uso geral em entradas não confiáveis.
- Ao converter YAML para JSON, espere perder comentários, strings multilinhas e âncoras - JSON é um subconjunto de YAML, e não o contrário para recursos.
- Recuar YAML com 2 espaços consistentemente – misturar tabulações e espaços ou usar recuo inconsistente é o erro de análise YAML mais comum.