JSON vs YAML: diferenças e casos de uso

JSON e YAML são os dois formatos de serialização textual mais utilizados para descrever dados estruturados: configuração de aplicação, payload de API, ficheiros de infraestrutura, manifests Kubernetes, pipelines CI/CD. Ambos representam as mesmas estruturas fundamentais (objetos, listas, escalares), mas com filosofias diferentes: o JSON privilegia a legibilidade pela máquina e a universalidade, o YAML aposta na legibilidade pelo humano e na concisão. Este artigo compara os dois formatos ponto por ponto para te ajudar a escolher.

O que é o JSON?

O JSON (JavaScript Object Notation) é um formato de serialização introduzido por Douglas Crockford no início dos anos 2000, derivado da sintaxe literal de objeto de JavaScript. Normalizado pelo RFC 8259 e pelo ECMA-404, é hoje o formato pivot da web: a quase totalidade das APIs REST, das bases NoSQL e das configurações frontend utiliza-o.

O JSON assenta em duas estruturas:

• Uma coleção ordenada de pares chave-valor (o objeto, entre chavetas)
• Uma lista ordenada de valores (o array, entre parênteses retos)

Os valores escalares são string, number, true, false ou null. As cadeias têm obrigatoriamente de estar entre aspas duplas. O JSON não suporta comentários.

O que é o YAML?

O YAML (YAML Ain't Markup Language) é um formato surgido em 2001, concebido desde o início para ser legível por um humano. A especificação atual é a YAML 1.2.2. A sua característica distintiva: usa a indentação para exprimir a hierarquia, à maneira do Python.

O YAML é um superconjunto do JSON desde a versão 1.2: qualquer documento JSON válido é um documento YAML válido. Mas o YAML acrescenta muito: comentários, cadeias sem aspas, multilinha, âncoras e aliases, tags para tipagem explícita, vários documentos no mesmo ficheiro (---).

Sintaxe comparada

Aqui está a mesma estrutura expressa nos dois formatos.

JSON

{
  "name": "cdrn",
  "version": "1.14",
  "tags": ["seo", "tools", "open-source"],
  "author": {
    "name": "Adrien",
    "email": "contact@example.com"
  },
  "active": true,
  "stars": null
}

YAML

# Configuracao do projeto
name: cdrn
version: "1.14"
tags:
  - seo
  - tools
  - open-source
author:
  name: Adrien
  email: contact@example.com
active: true
stars: null

Sobre o mesmo conteúdo, o YAML ocupa praticamente o mesmo número de linhas mas evita as chavetas, os parênteses retos, as vírgulas finais e as aspas na maior parte das cadeias. Os comentários (linhas #) são permitidos.

Tipos suportados

O JSON tem 6 tipos: object, array, string, number, boolean, null. Sem data nativa, sem binário, sem distinção explícita entre inteiro e flutuante.

O YAML 1.2 conhece os mesmos que o JSON e acrescenta: timestamps ISO 8601, binários (codificados em base64 através da tag !!binary), inteiros e floats distintos, o infinito, NaN, e os tipos personalizados através de tags (!!str, !!int, !!float...). O YAML 1.1 aceitava yes/no/on/off como booleanos: uma armadilha clássica nos parsers antigos.

Desempenho e ecossistema

O JSON é tipicamente 3 a 10 vezes mais rápido a fazer parsing do que o YAML, e os seus parsers estão disponíveis em todo o lado (integrados no runtime da quase totalidade das linguagens). As bibliotecas YAML são mais pesadas porque suportam uma gramática mais rica (anchors, tags, multi-doc).

Do lado do ecossistema: o JSON domina as APIs HTTP, as bases NoSQL (MongoDB, CouchDB), os ficheiros package.json, composer.json, tsconfig.json. O YAML impôs-se para a configuração aplicacional e o infrastructure-as-code: Symfony, Spring Boot, Rails, Docker Compose, Kubernetes, GitHub Actions, GitLab CI, Ansible.

Tabela comparativa

Casos de uso típicos

Escolher JSON quando

• Conceber uma API REST ou um endpoint webhook
• Armazenar dados numa base NoSQL ou numa cache
• Trocar dados entre frontend e backend
• O desempenho de parsing é crítico (alto débito, edge)
• Queres um formato universalmente suportado sem dependências

Escolher YAML quando

• Escreves uma configuração aplicacional editada à mão
• Precisas de comentários para documentar as opções
• Escreves Kubernetes, Docker Compose, GitHub Actions, Ansible
• Queres fatorizar blocos com âncoras e aliases
• A legibilidade prevalece sobre a rapidez de processamento

Recomendação

A regra simples: JSON para a máquina, YAML para o humano. Se o teu ficheiro é produzido ou consumido por um programa, opta por JSON. Se é escrito e relido à mão, opta por YAML. Muitos ecossistemas aceitam ambos: o Symfony lê YAML, JSON e XML para as suas configurações, o Kubernetes aceita ambos para os seus manifests. Na dúvida, vai de YAML para a configuração humana e JSON para os fluxos automatizados.

Podes testar a conversão de um formato para o outro com o nosso conversor JSON / YAML e formatar rapidamente um documento com o formatador JSON.

Perguntas frequentes