Tutorial de Sintaxe YAML: Uma Introdução Prática

YAML (YAML Ain't Markup Language) é um formato de serialização de dados legível por humanos, amplamente utilizado em arquivos de configuração, pipelines CI/CD e infraestrutura como código. Se você trabalha com Docker Compose, Kubernetes, GitHub Actions ou Ansible, já está usando YAML diariamente. Este tutorial cobre tudo o que você precisa para escrever YAML com confiança.

Por Que YAML?

A principal vantagem do YAML é a legibilidade. Compare os mesmos dados em JSON e YAML:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML alcança a mesma estrutura com menos pontuação. Sem chaves, sem colchetes para casos simples, sem aspas obrigatórias. Isso torna os arquivos de configuração mais fáceis de ler e editar manualmente.

Tipos de Dados Básicos

Escalares

O YAML infere tipos automaticamente a partir dos valores:

string: hello world          # String (sem necessidade de aspas)
quoted: "hello world"        # String explícita
integer: 42                  # Inteiro
float: 3.14                  # Ponto flutuante
boolean: true                # Booleano (true/false, yes/no, on/off)
null_value: null             # Nulo (também ~ ou vazio)
date: 2025-01-15             # Data (ISO 8601)

Armadilha comum: Valores como yes, no, on, off são interpretados como booleanos. Se você quer a string "yes", use aspas: "yes".

Strings e Aspas

Strings raramente precisam de aspas, mas alguns casos exigem:

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

Strings Multilinhas

O YAML tem dois estilos multilinhas:

Bloco literal (|) — preserva quebras de linha:

description: |
  Esta é a linha um.
  Esta é a linha dois.
  
  Esta é a linha quatro (após linha em branco).

Bloco dobrado (>) — une linhas com espaços:

description: >
  Este é um parágrafo longo
  que será dobrado em
  uma única linha.

Adicione - para remover newlines finais (|-, >-) ou + para mantê-los (|+, >+).

Coleções

Listas (Sequências)

# Estilo block
fruits:
  - apple
  - banana
  - cherry

# Estilo flow (inline)
fruits: [apple, banana, cherry]

Mapas (Mapeamentos)

# Estilo block
person:
  name: Alice
  age: 30
  city: London

# Estilo flow
person: {name: Alice, age: 30, city: London}

Estruturas Aninhadas

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

Âncoras e Aliases

Âncoras (&) e aliases (*) permitem reutilizar valores:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Sobrescreve o padrão

A chave de merge << incorpora todas as propriedades da âncora. Propriedades definidas após o merge sobrescrevem os valores ancorados. Leia mais sobre padrões avançados de âncoras em nosso guia de âncoras e aliases YAML.

Múltiplos Documentos

Um único arquivo YAML pode conter múltiplos documentos separados por ---:

---
# Documento 1: Config
apiVersion: v1
kind: ConfigMap
---
# Documento 2: Service
apiVersion: v1
kind: Service

Isso é comumente usado em manifestos Kubernetes.

Armadilhas Comuns

1. Erros de Indentação

YAML usa espaços, nunca tabs. Indentação inconsistente é o erro mais comum:

# ERRADO - indentação mista
server:
  host: localhost
    port: 8080  # Erro: indentação inesperada

# CORRETO
server:
  host: localhost
  port: 8080

Use nosso Formatador YAML para corrigir automaticamente problemas de indentação.

2. O Problema da Noruega

Códigos de país como NO (Noruega) são interpretados como booleano false:

# ERRADO
countries:
  - NO  # Interpretado como false!
  - SE
  - DK

# CORRETO
countries:
  - "NO"
  - SE
  - DK

3. Caracteres Especiais Sem Aspas

Dois-pontos, cerquilhas e colchetes em valores precisam de aspas:

# ERRADO
message: Error: file not found
url: http://example.com  # Pode quebrar

# CORRETO
message: "Error: file not found"
url: "http://example.com"

4. Problema com Números de Versão

Números de versão como 1.0 são interpretados como ponto flutuante:

# ERRADO
version: 1.0  # Vira 1 (float)

# CORRETO
version: "1.0"  # String

Validando YAML

Sempre valide seu YAML antes de fazer deploy. Erros de sintaxe em YAML podem causar falhas obscuras em aplicações. Nosso Validador YAML verifica a sintaxe instantaneamente, destacando a linha e coluna exatas de quaisquer erros.

Para um aprofundamento nas diferenças entre YAML e JSON, veja nossa comparação YAML vs JSON.

FAQ

Quantos espaços devo usar para indentação YAML?

Dois espaços é a convenção mais comum, usada pelo Kubernetes, Docker Compose, GitHub Actions e a maioria das ferramentas DevOps. Alguns projetos usam quatro espaços. A regra principal é consistência dentro do arquivo — nunca misture níveis de indentação.

YAML suporta comentários?

Sim, YAML suporta comentários de linha única com #. Não existe sintaxe para comentários multilinhas. Comentários são removidos durante o parsing e não ficam disponíveis na estrutura de dados carregada.

Recursos Relacionados

• Formatador YAML — Formate e embeleze arquivos YAML
• YAML vs JSON — Quando usar cada formato
• YAML para Docker Compose — Padrões YAML específicos para Docker