Noções básicas de YAML

A indentação é a sintaxe

No YAML, o espaço em branco não é decoração — é a estrutura inteira. Um mapeamento é uma chave, dois-pontos, um espaço e, então, um valor; um valor aninhado é escrito na linha seguinte, mais indentado, e duas linhas na mesma indentação são irmãs. Tabs são proibidos de plano: a especificação não consegue decidir a largura de um tab, então os parsers os rejeitam em vez de adivinhar. Editores continuam inserindo tabs ao copiar e colar, e é por isso que tantos arquivos parecem perfeitos e se recusam a fazer parse.

A convenção é dois espaços por nível. Quatro ou seis são igualmente válidos — a especificação só proíbe tabs —, mas dois é o que o Kubernetes e o Compose usam, o que todo linter espera e o que impede manifests profundos de rolar para o lado. Misturar larguras dentro de um arquivo é assim que nascem os erros de indentação, então escolha dois e deixe o editor garantir isso.

• Um nível = qualquer contagem fixa de espaços; dois é a convenção.
• Tabs na indentação são rejeitados pelos parsers, não convertidos.
• Um item de sequência pode ficar na indentação da chave-pai — o hífen é o marcador.
• Valores também podem ser escritos inline no estilo de fluxo: ports: [8080].

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

Escalares e o problema da Noruega

Valores entre aspas são strings, sempre. Valores sem aspas ganham tipo por inferência, e a inferência é de onde vem a reputação do YAML: um 8080 sem aspas se torna o número 8080 e um valor vazio se torna null, o que ajuda — até a inferência tipar algo que você queria como texto, como um código de país ou uma string de versão.

A falha clássica é uma lista de códigos de país ISO em que NO — Noruega — faz parse como booleano false: o problema da Noruega, engraçado até desligar silenciosamente uma flag de deploy. A versão 1.1 foi muito mais longe, como a tabela mostra. O core schema do 1.2 resolve apenas true e false como booleanos e lê o restante da tabela abaixo como strings simples ou números decimais — mas, como tanto software em produção ainda aplica regras do 1.1, o hábito defensivo é colocar entre aspas tudo o que precisa permanecer string.

Aspas e escalares de bloco

O YAML oferece três formas de escrever uma string. Sem aspas é o padrão e funciona para a maioria dos valores. Aspas simples são literais — o único escape é duplicar a aspa ('it''s fine'). Aspas duplas suportam escapes com barra invertida como \n e \t, o estilo que o JSON usa. A regra defensiva continua valendo: se um valor contém qualquer coisa que possa ser confundida com estrutura — dois-pontos, cerquilhas, palavras reservadas —, coloque aspas de propósito.

Texto multilinha usa escalares de bloco. Um bloco literal, escrito |, mantém cada nova linha exatamente como digitada — a forma certa para scripts de shell e certificados. Um bloco dobrado, escrito >, junta as linhas em um parágrafo fluido — a forma certa para uma descrição longa. Ambos aceitam um indicador de chomping: |- remove a última nova linha, |+ mantém todas as finais, e o | simples mantém exatamente uma.

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

Âncoras, aliases e reutilização

O YAML permite que um nó carregue um nome que outros nós referenciam. Escreva &name depois de uma chave para ancorar seu valor; escreva *name em qualquer outro lugar para criar um alias, e o parser substitui por uma cópia do nó ancorado. Jobs que compartilham uma política de retry apontam, então, para uma única definição, e a mudança é feita uma vez só.

Duas extensões se apoiam nesse mecanismo. Chaves de merge, escritas <<: *name, enxertam todas as chaves de um mapeamento ancorado na atual — comuns em arquivos Compose e Ansible, e uma convenção da era 1.1 que nunca entrou na gramática central do 1.2. Âncoras também podem ser abusadas: aliases aninhados dentro de aliases fazem dez definições se expandirem para um milhão de nós — o ataque billion-laughs —, então parsers confiáveis estabelecem um orçamento de expansão e relatam o limite em vez de travar.

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

Comentários e múltiplos documentos

Comentários começam com # e vão até o fim da linha; uma cerquilha dentro de uma string entre aspas não conta. Essa é a maior vitória ergonômica do YAML sobre o JSON, que removeu comentários por design, e a razão pela qual a configuração mantida por humanos gravita para cá: o arquivo se explica inline, e as revisões citam uma linha e seu comentário em um único hunk de diff.

Um arquivo também pode conter vários documentos, separados por linhas de três hífens; um --- no começo é o marcador opcional de início e ... encerra um documento. É assim que um único artefato carrega uma configuração de staging e uma de produção lado a lado. Os conversores deste site fazem parse de todos os documentos e operam sobre o último, acompanhando o comportamento comum de CLIs.

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

O que os conversores deste site aceitam

Todo parser de YAML é um parser de um subconjunto — a gramática 1.2 completa é notoriamente grande —, e um conversor conquista confiança ao declarar seu subconjunto em vez de deixar você descobri-lo por falhas. A biblioteca YAML deste site implementa o core schema do 1.2 sobre as construções de bloco e de fluxo que aparecem em arquivos de configuração reais, com limites deliberados onde a especificação permite trabalho ilimitado. A tabela é o contrato.