JSON vs YAML em arquivos de configuração

JSON e YAML muitas vezes representam o mesmo modelo de dados: objetos, arrays, strings, números, booleanos e null. A diferença está em como se comportam em arquivos editados por humanos e em pipelines gerados por máquina.

Escolha o formato conforme quem edita e o quão rígido o pipeline precisa ser.

JSON é estrito e previsível

JSON combina quando máquinas produzem ou consomem o arquivo:

• Exemplos de request e response de API.
• Metadados de pacotes.
• Configuração gerada.
• Troca de dados entre serviços.
• Fixtures de teste que devem fazer parse igual em todo lugar.

A sintaxe estrita pode parecer barulhenta, mas reduz ambiguidade. Strings precisam de aspas, vírgulas importam e parsers em geral concordam.

Use o Formatador JSON para validar, inspecionar ou normalizar um payload JSON rapidamente.

YAML é amigável para config editada à mão

YAML é popular em arquivos que humanos mantêm:

• Manifests Kubernetes.
• Workflows GitHub Actions.
• Arquivos Docker Compose.
• Configuração de aplicação.
• Exemplos em documentação.

É mais fácil de ler com aninhamento profundo e comentários. O trade-off: indentação, tipagem implícita e arquivos multi-documento podem surpreender.

Use o Formatador / Validador YAML antes de aplicar ou commitar YAML importante.

Onde YAML falha

Problemas comuns:

• Tabs onde se esperam espaços.
• on, yes ou no interpretados de forma inesperada.
• Dois documentos colados em um arquivo.
• Indentação que parece certa mas muda a estrutura.
• Comentários perdidos na conversão automatizada.

São gerenciáveis, mas riscos operacionais reais.

Onde JSON falha

Problemas comuns:

• Vírgulas finais copiadas de JavaScript.
• Comentários em arquivos que parsers JSON estritos rejeitam.
• Strings escapadas difíceis de ler.
• Arquivos grandes difíceis de editar à mão.

JSON é mais seguro para máquinas, nem sempre mais gentil com humanos.

Regra prática

Use JSON quando a troca estrita importa. Use YAML quando humanos precisam de config legível com comentários. Converta com cuidado, valide antes do deploy e não assuma que os dois formatos preservam todo detalhe nos dois sentidos.