JSON vs YAML: diferencas e quando usar cada um

YAML e um superconjunto do modelo de dados do JSON: todo documento JSON valido e tambem YAML valido, palavra por palavra. A diferenca nao e o que cada formato pode representar, mas como cada um e escrito e o quanto cada um e confortavel para editar manualmente.

Os mesmos dados, duas maneiras

{
  "name": "web-app",
  "version": "1.0.0",
  "scripts": { "build": "vite build", "test": "vitest" },
  "dependencies": ["react", "vite"]
}

name: web-app
version: 1.0.0
scripts:
  build: vite build
  test: vitest
dependencies:
  - react
  - vite

Mesmo documento, mesmos dados uma vez analisados. YAML remove as chaves, colchetes, aspas em cadeias simples e a maioria das virgulas, e usa indentacao para mostrar o aninhamento no lugar.

Onde realmente diferem

Comentarios. YAML tem, # assim. JSON nao tem nenhum, por projeto; um arquivo de configuracao .json com uma explicacao ao lado de uma configuracao precisa colocar essa explicacao em outro lugar, geralmente um README, porque o analisador rejeitara uma linha com // ou # de imediato. Sozinha, essa e a razao pela qual configuracao mantida a mao (pipelines CI, Docker Compose, manifestos Kubernetes) usa YAML por padrao: a pessoa que edita um ano depois precisa saber por que uma configuracao e como e, e um comentario e o unico lugar que sobrevive ao lado do valor.

Sensibilidade ao espaco. A indentacao do YAML e estrutural, da mesma maneira que a do Python. Dois espacos em vez de quatro, ou uma tabulacao onde um espaco era esperado, muda o que o documento significa ou quebra nao hora, e a mensagem de erro para uma indentacao ruim e frequentemente menos especifica que o “token inesperado na linha 4, coluna 12” de um analisador JSON. As chaves e colchetes do JSON sao explicitos, entao a indentacao e apenas cosmica, o que faz parte da razao pela qual JSON e o formato que maquinas geram e consomem: um script nao se preocupa com legibilidade e prefere delimitadores sem ambiguidade.

Multiplas maneiras de escrever o mesmo valor. YAML tem um escalar simples, uma cadeia entre aspas simples, uma cadeia entre aspas duplas, escalares de bloco para texto multi-linha, ancoragens e aliases para repetir um valor por referencia, e algumas conversoes de tipo implicitas (yes e no eram analisados como booleanos no YAML 1.1, que e exatamente o tipo de surpresa que fez o “problema da Noruega”, um codigo de pais NO lido como falso booleano, se tornar um erro conhecido do YAML). JSON tem uma maneira de escrever uma cadeia, uma maneira de escrever um numero, e nenhuma conversao implicita. Menos maneiras de escrever a mesma coisa sao menos maneiras de escreve-la errado, que e o verdadeiro argumento para JSON em uma carga maquina a maquina.

Tamanho alem da verbosidade e comentarios. Uma vez que o espaco e removido, JSON e YAML comprimem para tamanhos comparaveis para os mesmos dados; a vantagem do YAML e a legibilidade quando uma pessoa o edita, nao a contagem bruta de bytes.

Quando usar cada um

• JSON para qualquer coisa que um programa gera e outro programa consome sem que um ser humano leia no meio: cargas de API, intercambio de dados, qualquer coisa serializada e deserializada no mesmo ciclo requisicao-resposta.
• YAML para qualquer coisa que uma pessoa edita regularmente a mao e precisa de comentarios ou cadeias multi-linha para se manter: configuracao de CI, manifestos Kubernetes, arquivos de configuracao de aplicacoes que vem com documentacao em linha.

Boas ferramentas aceitam ambos e convertem internamente, o que geralmente e mais util do que escolher um lado permanente: escreva a configuracao no formato que as pessoas que a mantem preferem, e converta para JSON no ponto onde outra coisa precise consumi-la programaticamente.

Convertendo entre eles

O Conversor JSON para YAML funciona nas duas direcoes: escreve ancoragens, aliases e fluxos multi-documento corretamente em vez de achatar tudo em escalares simples, e ao ler YAML de volta coloca entre aspas qualquer coisa que nao faria o ciclo completo como o tipo com que comecou (uma cadeia de versao como "1.0" continua sendo cadeia, nao o numero 1). Nada do que voce converter e enviado; a conversao roda no seu navegador igual a cada ferramenta neste site.