# Referência Rápida de YAML

*Escalares, sequências, mapeamentos, âncoras, multi-linha*

> Source: YAML Specification (yaml.org) · MIT

## Sintaxe

### Regras Básicas

| Command | Description |
|---------|-------------|
| `Indentação` | Apenas espaços (sem tabs), profundidade consistente |
| `#` | Comentário (até o final da linha) |
| `---` | Marcador de início de documento |
| `...` | Marcador de fim de documento |
| `Sensível a maiúsculas` | Chaves e valores diferenciam maiúsculas e minúsculas |

### Exemplo Mínimo

```
---
name: Alice
age: 30
active: true
```

## Escalares

### Tipos de Escalar

| Command | Description |
|---------|-------------|
| `hello` | String (sem aspas) |
| `"hello"` | String (aspas duplas, permite escapes) |
| `'hello'` | String (aspas simples, literal) |
| `42 / 3.14` | Número (inteiro / decimal) |
| `true / false` | Booleano |
| `null / ~` | Valor nulo |
| `2026-03-26` | Data (ISO 8601) |

### Regras de Aspas

```
plain: sem aspas necessárias
special: "dois-pontos: e cerquilha # precisam de aspas"
escape: "linha\nnova"
literal: 'sem \n escape aqui'
```

## Sequências

### Sequência em Bloco

```
fruits:
  - apple
  - banana
  - cherry
```

### Sequência de Fluxo (Em Linha)

```
colors: [red, green, blue]
matrix: [[1, 2], [3, 4]]
```

### Sequência de Objetos

```
users:
  - name: Alice
    role: admin
  - name: Bob
    role: user
```

## Mapeamentos

### Mapeamento em Bloco

```
server:
  host: localhost
  port: 8080
  debug: false
```

### Mapeamento de Fluxo (Em Linha)

```
point: {x: 10, y: 20}
```

### Chaves Complexas

```
? [first, second]
: "valor de chave composta"
```

## Âncoras e Aliases

### Definir e Reutilizar

```
defaults: &defaults
  timeout: 30
  retries: 3
production:
  <<: *defaults
  timeout: 60
```

### Referência

| Command | Description |
|---------|-------------|
| `&name` | Definir uma âncora |
| `*name` | Referenciar (alias) uma âncora |
| `<<` | Chave de mesclagem — mesclar mapeamento no atual |

## Strings Multi-linha

### Escalares em Bloco

| Command | Description |
|---------|-------------|
| `\| (literal)` | Preserva quebras de linha exatamente |
| `> (dobrado)` | Dobra quebras de linha em espaços |
| `\|+ (manter)` | Literal, manter quebras de linha finais |
| `\|- (remover)` | Literal, remover quebras de linha finais |
| `>- (dobrar+remover)` | Dobrado, remover quebras de linha finais |

### Bloco Literal

```
script: |
  echo "line one"
  echo "line two"
```

### Bloco Dobrado

```
description: >
  Este texto longo será
  dobrado em uma única linha
  com espaços.
```

## Tags

### Tags de Tipo

| Command | Description |
|---------|-------------|
| `!!str 42` | Forçar valor para string "42" |
| `!!int "42"` | Forçar valor para inteiro 42 |
| `!!float 1` | Forçar valor para decimal 1.0 |
| `!!bool "true"` | Forçar valor para booleano |
| `!!null ""` | Forçar valor para nulo |
| `!!binary` | Dados binários codificados em Base64 |

### Exemplo de Tag

```
port: !!str 8080
enabled: !!bool "yes"
version: !!float 3
```

## Padrões Comuns

### Docker Compose

```
services:
  web:
    image: nginx:alpine
    ports: ["80:80"]
    environment:
      NODE_ENV: production
```

### GitHub Actions

```
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
```

### Dicas

| Command | Description |
|---------|-------------|
| `yamllint` | Validar YAML quanto a sintaxe e estilo |
| `yq` | Processador YAML de linha de comando (como jq) |
| `Evitar Norway` | NO é false booleano — colocar aspas em códigos de países |
| `Evitar !!python` | Nunca carregar YAML não confiável com carregadores inseguros |