YAML explicado + JSON vs. YAML

Se você já editou um arquivo de configuração de uma ferramenta moderna — Docker Compose, GitHub Actions, Kubernetes — você escreveu YAML. Ele é projetado para ser o formato de dados mais legível para pessoas, mas essa legibilidade vem com algumas arestas afiadas. Este guia explica como o YAML funciona, as ciladas a vigiar e como ele se compara ao JSON.

O que é YAML

YAML (“YAML Ain’t Markup Language”) é um formato de dados para representar as mesmas coisas que o JSON — pares chave/valor, listas e estruturas aninhadas — mas com uma sintaxe ajustada para as pessoas lerem e escreverem à mão. É a escolha padrão para arquivos de configuração justamente por ser fácil de percorrer com os olhos.

name: RunWebTools
active: true
tags:
  - json
  - free
address:
  city: London
  postcode: null

Como a sintaxe funciona

Três ideias cobrem a maior parte do YAML:

• A indentação mostra a estrutura. O aninhamento é expresso com espaços, não com chaves. Itens no mesmo nível de indentação são irmãos.
• Pares chave/valor usam key: value (o espaço depois dos dois-pontos é obrigatório).
• Listas usam um - inicial em cada item.

As ciladas

Espaços, nunca tabulações

O YAML proíbe caracteres de tabulação para indentação — eles causam um erro de análise. Configure seu editor para inserir espaços, porque os dois parecem idênticos na tela, mas só um é válido.

O “problema da Noruega”

O YAML tenta adivinhar os tipos, o que de vez em quando sai pela culatra. Sem aspas, no, yes, on e off viram booleanos — é famoso que o código de país NO da Noruega pode virar false. Quando você quer uma string literal, ponha entre aspas: "NO".

Erros de indentação são silenciosos

Como o espaço em branco carrega significado, uma única linha desalinhada pode mudar a estrutura sem erro algum — o arquivo simplesmente é analisado como algo que você não pretendia. Passá-lo por um validador de YAML que reemite o resultado analisado é o jeito mais rápido de ver o que o YAML realmente entendeu.

YAML vs. JSON

Eles podem representar os mesmos dados — na verdade, todo JSON válido também é YAML válido. As compensações:

• Legibilidade: o YAML vence para pessoas — sem chaves ou aspas, e ele suporta comentários (#), o que o JSON não faz.
• Rigor: o JSON vence para máquinas — sua sintaxe rígida deixa pouco espaço para a adivinhação de tipos e as surpresas de indentação que o YAML permite.
• Caso de uso: recorra ao YAML para arquivos que pessoas editam (configuração) e ao JSON para dados que programas trocam (APIs).

Precisa passar de um para o outro? Formate e confira qualquer um com o formatador de YAML e o formatador de JSON. Se o YAML parece implicante, nosso guia sobre JSON e seus erros comuns é uma boa leitura complementar.