JSON vs XML vs YAML: como escolher o formato de dados certo

Os mesmos dados, de três maneiras

Abaixo, um pequeno objeto escrito nos três formatos. Comparando-os lado a lado, você vê o que cada formato sacrifica.

{
  "user": {
    "name": "Ada Lovelace",
    "roles": ["admin", "editor"],
    "active": true
  }
}

user:
  name: Ada Lovelace
  roles:
    - admin
    - editor
  active: true

<user active="true">
  <name>Ada Lovelace</name>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
</user>

Três campos, três quantidades muito diferentes de pontuação. Essa diferença é a história toda: o JSON é o mais amigável para máquinas, o YAML é o mais amigável para escrever à mão, e o XML é o mais expressivo quando o próprio documento precisa de estrutura que vai além de simples dados chave/valor.

Onde o JSON vence

O JSON mapeia diretamente para as estruturas de dados que toda linguagem popular já possui (objetos/dicts e arrays/lists), então a análise gera tipos nativos sem ambiguidade. Ele não tem comentários, tem uma só forma de escrever cada valor e não é sensível a espaços em branco. Esses limites o tornam rápido de analisar e seguro de gerar por código.

Use JSON para qualquer comunicação máquina-a-máquina: payloads de APIs REST e GraphQL, dados passados entre serviços, qualquer coisa armazenada em um banco de documentos (MongoDB, o JSONB do PostgreSQL) e qualquer configuração que seja principalmente lida e escrita por código, e não editada à mão.

Onde o YAML vence

O YAML é um superconjunto estrito do modelo de dados do JSON com uma sintaxe muito mais amigável para humanos: sem colchetes de fechamento para contar, comentários com # e indentação no lugar de pontuação. É isso que você quer para arquivos que uma pessoa edita e relê num diff: pipelines de CI (GitHub Actions, GitLab CI), manifests do Kubernetes e configuração de aplicação.

Essa flexibilidade é também a maior armadilha do YAML. Um erro de indentação produz uma estrutura diferente sem nenhum erro de análise, e o parser pode converter valores sem aspas como `no`, `yes`, `on` e datas em booleanos ou timestamps que você não pretendia (o infame 'problema da Noruega', em que o código de país NO vira o booleano false). Coloque aspas nas strings sempre que um valor puder ser lido de dois jeitos.

Onde o XML vence

O XML parece um legado pesado ao lado do JSON, mas faz coisas que nem JSON nem YAML conseguem: atributos junto ao conteúdo do elemento, conteúdo misto (texto e elementos intercalados, como no HTML), namespaces para combinar vocabulários de fontes diferentes, e validação madura por schema (XSD) e transformação (XSLT) com ferramentas uma década mais velhas que o JSON.

O XML persiste em domínios centrados em documentos: APIs SOAP, SVG, DOCX/XLSX (arquivos ZIP cheios de XML) e sistemas corporativos de bancos, saúde e governo, com pipelines validados por XSD que ninguém vai reescrever. Se seus dados têm formato de documento ('um parágrafo com um trecho em negrito no meio') em vez de registro, o XML costuma se encaixar melhor.

Convertendo entre formatos

Os três descrevem o mesmo modelo de dados objeto/array/string/número/booleano/null (só os atributos e o conteúdo misto do XML não mapeiam de forma limpa), então converter dados em formato de registro entre JSON, YAML e XML é mecânico. As ferramentas JSON to YAML, YAML to JSON, JSON to XML e XML to JSON do JSONForge convertem no navegador, o que ajuda quando você migra o formato de um arquivo de configuração ou precisa entregar um export em JSON para um colega que só usa YAML.