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 ficheiros de configuração, pipelines CI/CD e infraestrutura como código. Se trabalha com Docker Compose, Kubernetes, GitHub Actions ou Ansible, já utiliza YAML diariamente. Este tutorial abrange tudo o que precisa para escrever YAML com confiança.

Porquê 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

O YAML alcança a mesma estrutura com menos pontuação. Sem chavetas, sem parênteses retos para casos simples, sem aspas obrigatórias. Isto torna os ficheiros de configuração mais fáceis de ler e editar manualmente.

Tipos de Dados Básicos

Escalares

O YAML infere automaticamente os tipos a partir dos valores:

string: hello world          # String (sem aspas necessárias)
quoted: "hello world"        # String explícita
integer: 42                  # Inteiro
float: 3.14                  # Float
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 pretende a string "yes", coloque-a entre aspas: "yes".

Strings e Aspas

As strings raramente precisam de aspas, mas alguns casos exigem-nas:

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 Multilinha

O YAML tem dois estilos multilinha:

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 (>) — junta linhas com espaços:

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

Adicione - para remover novas linhas finais (|-, >-) ou + para as manter (|+, >+).

Coleções

Listas (Sequências)

# Estilo block
fruits:
  - apple
  - banana
  - cherry

# Estilo flow (em linha)
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

As âncoras (&) e aliases (*) permitem-lhe reutilizar valores:

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

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Sobrepõe o predefinido

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

Múltiplos Documentos

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

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

Isto é comummente utilizado em manifestos do Kubernetes.

Armadilhas Comuns

1. Erros de Indentação

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

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

# CORRETO
server:
  host: localhost
  port: 8080

Utilize o 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, cardinal e parênteses retos em valores precisam de aspas:

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

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

4. Armadilha dos Números de Versão

Números de versão como 1.0 são analisados como floats:

# ERRADO
version: 1.0  # Torna-se 1 (float)

# CORRETO
version: "1.0"  # String

Validar YAML

Valide sempre o seu YAML antes de implementar. Erros de sintaxe em YAML podem causar falhas crípticas em aplicações. O nosso Validador YAML verifica a sintaxe instantaneamente, destacando a linha e coluna exatas de quaisquer erros.

Para um aprofundamento das diferenças entre YAML e JSON, consulte a nossa comparação YAML vs JSON.

FAQ

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

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

O YAML suporta comentários?

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

Recursos Relacionados

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