YAML vs JSON: quando usar qual

YAML vs JSON: a versão curta

JSON é um formato de intercâmbio de dados: estrito, inequívoco e qualquer linguagem pode analisá-lo nativamente. YAML é um formato de configuração: aceita comentários e strings multilinhas e foi projetado para ser editado por pessoas em pull requests. Use JSON na conexão, YAML em arquivos mantidos por humanos — e converta entre eles quando um limite exigir.

O que realmente difere

Comentários

YAML tem comentários; JSON não. Nos arquivos de configuração isso é decisivo — a razão pela qual você sabe por que um tempo limite está definido como 3000 geralmente é o comentário acima dele. Quando você converte YAML em JSON, os comentários são eliminados, e é por isso que JSON é frequentemente tratado como um artefato de construção, e não como a fonte da verdade.

Sintaxe e ruído

                # YAML
service:
  name: checkout
  replicas: 3
  ports: [8080, 9090]

// JSON — same data
{
  "service": {
    "name": "checkout",
    "replicas": 3,
    "ports": [8080, 9090]
  }
}
              

YAML remove colchetes, aspas e vírgulas em troca da sensibilidade ao recuo. Esse é o negócio que todo usuário YAML conhece: menos caracteres, mais maneiras de errar sutilmente os espaços em branco.

Tipos e armadilhas

• JSON possui um tipo numérico; YAML distingue ints, floats e muito mais — e YAML 1.1 analisa o famoso código de país NO como o booleano falso, e 1.10 como um número que perde seu zero à direita, a menos que seja citado.
• YAML suporta âncoras e aliases (&defaults / *defaults) para reutilização; JSON não tem equivalente, então os blocos compartilhados devem ser duplicados ou gerados.
• YAML suporta arquivos com vários documentos (--- separadores); JSON é um documento por arquivo. Os conversores normalmente transformam documentos em uma matriz.
• JSON requer chaves e strings entre aspas duplas; YAML cita apenas quando necessário, o que significa que uma string descuidada pode silenciosamente se tornar um número ou booleano.

Onde cada formato ganha

• APIs e formatos de conexão: JSON. Analisadores universais, ambiguidade previsível, fácil de transmitir (JSON Linhas).
• Kubernetes, CI/CD, Docker Compose, Ansible, Helm: YAML, porque esses ecossistemas se padronizaram nele e suportam comentários.
• Configuração do fornecedor que você gera programaticamente: JSON — algoritmos a produzem sem ansiedade de indentação.
• Documentos que um colega júnior editará manualmente: YAML, com comentários explicando o porquê.

Convertendo com segurança

1. Conheça seus arquivos de vários documentos. Um conjunto de manifestos k8s separado por --- deve se tornar um array JSON, não apenas o primeiro documento. Use um conversor que informe quantos documentos foram encontrados.
2. Cite os números que são identificadores. "1.10" é uma versão; 1.10 é um flutuador. Habilite aspas forçadas ao converter para YAML se os valores forem strings que parecem numéricas.
3. Observe os comentários desaparecendo. Converter para JSON tem perdas por definição; se os comentários forem importantes, mantenha YAML como fonte e gere JSON somente no momento da compilação.
4. Valide com erros precisos. Erros de indentação produzem mensagens enganosas em algumas ferramentas; certifique-se de que o seu mostre linha e coluna.

Experimente: cole qualquer YAML no conversor de YAML para JSON — o suporte a vários documentos e linhas de erro precisas estão integrados e nada é carregado.

Perguntas comuns

YAML é um superconjunto de JSON?

YAML 1.2 é projetado como um superconjunto – JSON válido geralmente é válido YAML. Mas YAML 1.1 (ainda disponível) difere em alguns casos extremos, e guias, chaves duplicadas e certas strings são analisadas de maneira diferente entre os mecanismos. Trate “é tecnicamente válido YAML” como uma curiosidade, não como uma estratégia de migração.

Qual é mais rápido de analisar?

JSON analisadores são geralmente mais rápidos e simples porque a gramática é menor; a análise JSON nativa existe em todos os tempos de execução. Para arquivos de configuração, a diferença é irrelevante – você analisa uma vez na inicialização.