YAML para iniciantes: Dominando arquivos de configuração

Se você trabalha com Docker, Kubernetes, GitHub Actions ou praticamente qualquer ferramenta moderna de DevOps, já está usando YAML, perceba ou não. YAML (que significa "YAML Ain't Markup Language" — sim, é um acrônimo recursivo) foi projetado para ser o formato de dados mais legível possível por humanos.

Vamos aprender juntos, um conceito de cada vez.

Por que o YAML existe

JSON é ótimo para máquinas, mas você já tentou escrever um arquivo de configuração de 200 linhas em JSON? Sem comentários, aspas duplas obrigatórias em todo lugar, chaves aninhadas em cinco níveis de profundidade... fica doloroso rápido. YAML foi criado para resolver isso. Ele usa indentação em vez de colchetes, o que deixa as configurações limpas e fáceis de ler.

Aqui estão os mesmos dados em JSON e YAML. Veja a diferença?

JSON:

YAML:

O básico que você precisa saber

Pares chave-valor são a base do YAML. Basta usar dois pontos e um espaço: name: John Doe. É isso — não precisa de aspas para a maioria das strings.

A indentação é tudo. YAML usa espaços (nunca tabs!) para mostrar a estrutura. O padrão é 2 espaços por nível. Erre nisso e seu arquivo quebra. Sério — a especificação YAML é rigorosa quanto a isso.

Aqui está um exemplo de dados aninhados:

Listas usam um hífen e um espaço. Aqui está uma lista de compras em YAML:

Strings: Mais complicadas do que você imagina

A maioria das strings não precisa de aspas em YAML. Mas você deveria usá-las quando contêm dois pontos, cerquilhas ou poderiam ser mal interpretadas. Por exemplo, country: NO é interpretado como country: false no YAML 1.1 porque NO é tratado como booleano. Este é o infame "problema da Noruega" e já causou bugs reais em produção.

Na dúvida, coloque entre aspas: country: "NO"

Strings multilinha são incríveis

É aqui que o YAML realmente brilha. O pipe | preserva as quebras de linha (ótimo para scripts), enquanto > as converte em espaços (ótimo para descrições longas):

Âncoras e aliases: Arquivos de configuração DRY

Uma das funcionalidades mais legais do YAML. Defina algo uma vez com &, referencie depois com *:

O bloco production herda retries: 3 dos defaults mas sobrescreve timeout. Isso é incrivelmente útil em workflows do GitHub Actions e arquivos Docker Compose onde você repetiria os mesmos blocos de configuração várias vezes.

Os 4 erros mais comuns em YAML

• Tabs em vez de espaços — Seu editor pode inserir tabs por padrão. Configure-o para usar espaços em arquivos YAML. Sério, faça isso agora.
• Armadilhas de booleanos — yes, no, on, off, true, false são TODOS booleanos no YAML 1.1. Use aspas se quiser a string.
• Dois pontos em valores — message: Error: file not found vai quebrar porque o YAML vê um segundo separador chave-valor. Use aspas: message: "Error: file not found"
• Espaços no final — Espaços invisíveis no final das linhas podem causar comportamento estranho de parsing. Use um editor que destaque espaços no final.

Onde você usará YAML todos os dias

YAML é a linguagem de configuração para Docker Compose, manifestos Kubernetes, GitHub Actions, GitLab CI, playbooks Ansible e dezenas mais. Se você está fazendo qualquer coisa em DevOps ou cloud, fluência em YAML é inegociável.

Tem um arquivo YAML se comportando de forma estranha? Cole no nosso YAML Validator para encontrar o problema instantaneamente.

YAML no mundo real: Exemplo Docker Compose

Vamos olhar um arquivo Docker Compose realista — o tipo de coisa que você realmente escreveria para uma aplicação web:

Observe algumas coisas: as variáveis de ambiente podem ser escritas como lista (- KEY=value) ou como mapeamento (KEY: value). Ambas funcionam no Docker Compose — mas escolha um estilo e mantenha-o por consistência.

YAML no mundo real: Pipeline CI do GitHub Actions

Aqui está um workflow do GitHub Actions que executa testes a cada push:

Isso é limpo, legível e autoexplicativo. Imagine escrever esse mesmo workflow em JSON — seria o dobro do tamanho e muito mais difícil de ler visualmente.

YAML vs JSON vs TOML: Comparação rápida

YAML não é a única alternativa ao JSON para arquivos de configuração. TOML é outra escolha popular (usada pelo Cargo.toml do Rust e pyproject.toml do Python). Veja como se comparam:

YAML avançado: Múltiplos documentos em um arquivo

YAML suporta múltiplos documentos em um único arquivo, separados por ---. Isso é comumente usado no Kubernetes para implantar múltiplos recursos de uma vez:

O separador --- diz ao parser YAML "este é um novo documento." Você pode fazer kubectl apply -f em um arquivo assim e o Kubernetes criará ambos os recursos.

Segurança YAML: O ataque Billion Laughs

Aqui está algo que a maioria dos iniciantes não sabe: YAML pode ser um risco de segurança se você não tiver cuidado. O ataque "Billion Laughs" usa âncoras e aliases para criar expansão exponencial de dados:

Este arquivo minúsculo pode se expandir para gigabytes na memória e travar sua aplicação. A lição? Nunca faça parse de entrada YAML não confiável. Use funções de carregamento seguro como yaml.safe_load() em Python em vez de yaml.load(), e defina limites de memória no seu parser YAML.

Convertendo entre YAML e JSON

Como YAML é um superconjunto de JSON (sim, JSON válido também é YAML válido!), converter entre os dois é simples. Isso é útil quando você quer usar a legibilidade do YAML para escrever configurações mas precisa de JSON para uma API ou ferramenta que o exige.

Nosso Conversor de YAML para JSON faz isso instantaneamente — basta colar seu YAML e obter uma saída JSON limpa. Na direção oposta? Qualquer JSON que você tenha já é YAML válido.

Experimente você mesmo

Seja depurando um manifesto Kubernetes quebrado ou configurando um novo pipeline CI, essas ferramentas vão economizar seu tempo:

• YAML Formatter — Corrija a indentação e deixe seus arquivos YAML limpos e consistentes.
• YAML Validator — Detecte erros de sintaxe antes que quebrem seu deploy.
• Conversor de YAML para JSON — Converta entre formatos quando precisar interoperar com ferramentas que só aceitam JSON.

YAML tem suas peculiaridades, mas uma vez que você se acostume com a sintaxe baseada em indentação, vai apreciar o quanto seus arquivos de configuração ficam mais limpos comparados à alternativa JSON.