Skip to content

YAML Folha de referência

Padrão de serialização de dados amigável a humanos para arquivos de configuração.

01

Primeiros Passos

Estrutura Básica

YAML usa indentação (espaços, não tabs) para aninhamento. Mapeamentos usam chave: valor, sequências usam - item. A sintaxe inline usa [] para listas e {} para maps. Comentários usam #.

yaml
# YAML uses indentation for structure
# Comments start with #

# Key-value pairs (mappings)
name: Alice
age: 30

# Nested mappings (use consistent indentation)
person:
  name: Bob
  age: 25
  address:
    city: NYC
    zip: 10001

# Sequences (lists)
hobbies:
  - reading
  - coding
  - music

# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}

Comentários

Comentários começam com # e devem ser precedidos por espaço em branco ou início de linha. Dentro de block scalars (| e >), # é conteúdo literal, não comentário. Não há sintaxe de comentário multilinha — cada linha precisa do próprio #.

yaml
# Full-line comment
key: value  # Inline comment (whitespace before # required)

# Comments can appear anywhere
# - before documents
# - inside sequences
list:
  - a  # first item
  - b  # second item

# Block scalar headers DO accept comments
text: |  # literal block
  line one

# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
  # this is part of the string, not a comment

Regras de Indentação

YAML proíbe estritamente tabs para indentação — só espaços são permitidos. A indentação deve ser consistente dentro de um nível, mas não precisa ser um número fixo. O - em sequências faz parte da indentação. Misturar tabs e espaços lança erro de parser.

yaml
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention

mapping:
  nested:
    deeply_nested: value

# Sequences can be indented at the same level as the key
items:
  - one
  - two

# Or indented further (both are valid)
items2:
    - one
    - two

# WRONG: tab characters cause parser errors
# bad:	value   (tab before value)

# Hyphen counts as indentation start
- item1
- item2

Início e Fim de Documento

--- marca o início de um documento YAML; ... marca o fim. Um arquivo pode conter múltiplos documentos separados por --- (um fluxo de documentos). Para arquivos de configuração de documento único, um --- inicial é opcional, mas recomendado como dica aos parsers.

yaml
# --- separates documents in a stream
# ... ends a document (optional)

---
name: first document
value: 1
...
---
name: second document
value: 2
...

# A single document needs no markers
key: value

# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMap

Armadilhas Comuns

Os dois-pontos precisam de um espaço depois para serem separador de mapeamento. YAML 1.1 vs 1.2 diferem em yes/no/on/off (booleanos em 1.1, strings em 1.2) e em literais octais. Valores vazios são null, distintos de strings vazias. Muitos parsers (PyYAML) ainda seguem as regras 1.1.

yaml
# Colon needs a space after it
key:value      # WRONG: parsed as a single string "key:value"
key: value     # correct

# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes    # YAML 1.1: true; YAML 1.2: "yes" string

# Numbers with leading zeros
version: 010   # YAML 1.1: octal 8; YAML 1.2: string "010"

# Unquoted strings with special chars
url: example.com/path   # OK
url: example.com:8080   # WRONG: parsed as mapping with key example.com

# Empty values
empty:       # null
empty2: ~    # explicit null
empty3: ""   # empty string (different from null)

YAML vs JSON

YAML 1.2 foi projetado para que JSON seja um subconjunto estrito — qualquer arquivo JSON é YAML válido. YAML adiciona comentários, estrutura em bloco, âncoras, strings multilinha e tags. JSON exige aspas em todas as chaves e valores de string, o que o YAML relaxa para escalares simples.

yaml
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML

# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# Equivalent YAML:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents

# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)

# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.
02

Escalares (Strings, Números, Booleanos, Null)

Strings Simples e Entre Aspas

Strings simples dispensam aspas, a menos que pareçam números, booleanos, null ou datas. Aspas simples só escapam ' duplicando (''); nenhum outro escape. Aspas duplas suportam sequências de escape completas (\n, \t, \uXXXX). Colocar aspas força o tipo string.

yaml
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com

# Single-quoted — escape ' by doubling
msg: 'it''s fine'

# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1"   # Greek alpha
tab: "col1\tcol2"

# Multi-word plain strings are fine
description: This is a plain string with spaces

# Strings that look like other types must be quoted
version: "1.0"      # string, not float
notBool: "true"     # string, not boolean
notNull: "null"     # string, not null
date: "2024-01-01"  # string, not date

Números

YAML 1.2 usa 0o para octal (YAML 1.1 usava um 0 inicial solto). Underscores em números são permitidos por legibilidade. .inf e .nan são literais float especiais. Coloque aspas em qualquer valor que deva ser string, mas pareça numérico (versões, telefones, IDs).

yaml
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000   # readable grouping (YAML 1.2)

# Octal & hex (YAML 1.2 prefixes)
octal: 0o17     # = 15 decimal
hex: 0xFF       # = 255 decimal
binary: 0b1010  # = 10 decimal

# Floats
pi: 3.14159
exp: 1.0e+3     # 1000.0
neg_exp: -2.5e-4

# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan

# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"

Booleanos

YAML 1.2 restringiu os booleanos a true/false (e True/False, TRUE/FALSE). YAML 1.1 (usado pelo PyYAML) trata yes/no/on/off/y/n como booleanos — fonte famosa de bugs (ex.: 'no', da Noruega → false). Sempre coloque aspas nessas strings se você as quer literalmente.

yaml
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false

# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1

# To force a string:
answer: "yes"      # always a string
option: "on"
flag: "y"

# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!

# Safe practice: quote if you mean the literal string
country: "no"   # Norway country code, not False

Valores Null

YAML aceita null, Null, NULL, ~ e um valor vazio como null. Um valor vazio (chave sem nada depois dos dois-pontos) é null, distinto de uma string vazia "". Parsers mapeiam null do YAML para o valor null da linguagem hospedeira (None, null, nil).

yaml
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5:             # empty value

# Distinguish null from empty string
empty_string: ""
null_value: null

# In sequences
list:
  - value
  - null         # explicit null item
  - another

# In nested structures
config:
  timeout: null   # explicitly unset
  retries: 3

# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nil

Datas e Timestamps

Datas e timestamps ISO 8601 são reconhecidos como tipos nativos pela maioria dos parsers. Um YYYY-MM-DD solto vira uma data; com hora, vira um datetime. Coloque aspas no valor para mantê-lo como string. Designadores de fuso (Z, +08:00) são suportados.

yaml
# Date (ISO 8601)
date: 2024-01-15

# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00

# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'

# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)

Inferência de Tipo

O sistema de tipos do YAML resolve escalares sem aspas via um schema. O schema Failsafe trata tudo como string; os schemas JSON e Core inferem int, float, bool, null, data. Use aspas ou tags explícitas (!!str, !!int) para sobrescrever a resolução quando necessário.

yaml
# YAML infers types from unquoted scalars
str: hello             # string
int: 42                # integer
float: 3.14            # float
bool: true             # boolean
null_val: null         # null
date: 2024-01-01       # date
list: [1, 2, 3]        # sequence

# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"

# Or with the !!str tag
forced: !!str 42        # string "42"
forced_int: !!int "42"  # integer 42

# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferred
03

Mapeamentos

Mapeamento Simples

Um mapeamento é um conjunto de pares chave: valor, em que as chaves costumam ser strings. Chaves podem ser qualquer escalar (número, bool, até null). Chaves duplicadas são desencorajadas e o comportamento varia por parser (geralmente a última vence). Use um linter para pegar duplicatas acidentais.

yaml
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]

# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key

# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second   # overrides "first" in many parsers

# Values can be any type
mixed:
  string: text
  number: 42
  list: [1, 2, 3]
  nested:
    deep: value

Mapeamentos Aninhados

Mapeamentos aninhados são criados indentando as chaves filhas. A indentação deve ser consistente dentro de um nível. Não há tamanho fixo de indentação, mas 2 espaços é o padrão de fato. Aninhamento profundo reduz a legibilidade — considere achatar estruturas muito profundas.

yaml
# Nest mappings with consistent indentation
server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    cert: /etc/ssl/cert.pem
    key: /etc/ssl/key.pem

database:
  primary:
    host: db1.example.com
    port: 5432
  replica:
    host: db2.example.com
    port: 5432

# Indentation level is up to you — just be consistent
# 2 spaces is the most common convention

Mapeamento de Sequências

Mapeamentos e sequências se compõem livremente. Um padrão comum é uma sequência de mapeamentos (uma lista de registros), em que cada - inicia um item e as chaves alinhadas pertencem a ele. A indentação das chaves seguintes deve alinhar com a primeira chave depois do -.

yaml
# Values in a mapping can be sequences
servers:
  - web1.example.com
  - web2.example.com
  - web3.example.com

# Sequence of mappings (very common)
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# Each - starts a new item; aligned keys form one mapping
services:
  - name: api
    port: 8080
    env:
      - dev
      - prod
  - name: web
    port: 3000

# Mixed: mapping containing sequence containing mapping
config:
  endpoints:
    - path: /health
      method: GET
    - path: /users
      method: POST

Chaves Complexas

YAML permite qualquer escalar ou coleção como chave usando o indicador ? chave. Isso é raro em arquivos de configuração, mas útil para tabelas de consulta (ex.: preços por região+instância). Chaves complexas são difíceis de ler — a maioria dos arquivos de config fica com chaves de string simples.

yaml
# Keys can be complex objects using ? notation
? key1
: value1

# A mapping as a key
? host: localhost
  port: 8080
: connection1

# A sequence as a key
? [a, b, c]
: indexed_value

# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023

# In flow style:
{[a, b]: value, {x: 1}: other}

# Most config files just use plain string keys
simple: value

Mapeamentos Inline (Flow)

O estilo flow usa {} para mapeamentos e [] para sequências, parecido com JSON. Útil para dados curtos e compactos numa linha. Diferente do JSON, o YAML não permite vírgulas finais. Misture estilos flow e block livremente, mas prefira block pela legibilidade em arquivos de config.

yaml
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Mixed flow and block
block_key:
  flow_value: {x: 1, y: 2}
  another: value

# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}

# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}

# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,}   # parse error

Ordem e Estilo das Chaves

O YAML em si preserva a ordem dos mapeamentos na especificação, mas objetos da linguagem hospedeira podem não preservar (embora a maioria dos dicts modernos preservem). Para legibilidade da config, agrupe chaves relacionadas, use nomenclatura consistente (snake_case ou camelCase) e adicione comentários para delinear seções.

yaml
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered

# Consistent key style improves readability
config:
  server:
    host: localhost      # snake_case
    port: 8080
    max_connections: 100
  database:
    host: db.example.com
    port: 5432
    connection_pool: 10

# Group related keys together
# Use comments to delineate sections
app:
  # networking
  host: 0.0.0.0
  port: 3000
  # limits
  timeout: 30
  retries: 3
04

Sequências

Sequências em Bloco

Sequências em bloco usam - (hífen + espaço) antes de cada item. Itens podem ser de qualquer tipo: escalares, mapeamentos ou sequências aninhadas. O - conta como parte da indentação, então as chaves seguintes num item de mapeamento alinham com a primeira chave depois do hífen.

yaml
# A sequence (list) uses - followed by space
fruits:
  - apple
  - banana
  - cherry

# Sequence as top-level document
- item1
- item2
- item3

# Empty sequence
empty: []
or_with_marker: []

# Sequence with mixed types
mixed:
  - string
  - 42
  - true
  - null
  - key: value   # a mapping as an item

Sequências Aninhadas

Sequências aninhadas são formadas indentando mais níveis de -. Elas ficam difíceis de ler além de 2 níveis — troque para estilo flow nas sequências internas. Estruturas de árvore (sequência de mapeamentos com children) são mais legíveis que sequências puramente aninhadas.

yaml
# Sequence of sequences
matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

# More readable with flow style for inner
matrix2:
  - [1, 2, 3]
  - [4, 5, 6]

# Deeply nested
tree:
  - name: root
    children:
      - name: child1
        children:
          - name: grandchild1
      - name: child2

# 3D: sequence of sequence of sequence
cube:
  - - [1, 2]
    - [3, 4]
  - - [5, 6]
    - [7, 8]]

Sequência de Mapeamentos

Uma sequência de mapeamentos é o padrão YAML mais comum (listas de registros). Cada - inicia um novo item; chaves seguintes na mesma indentação pertencem àquele item. Alinhe as chaves depois do - por legibilidade. Um item de mapeamento vazio se escreve {}.

yaml
# Most common pattern: list of records
users:
  - name: Alice
    email: [email protected]
    roles:
      - admin
      - user
  - name: Bob
    email: [email protected]
    roles:
      - user

# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
  - host: web1.example.com
    port: 8080
    healthy: true
  - host: web2.example.com
    port: 8080
    healthy: false

# Empty mapping item
list:
  - {}
  - name: real

Sequências Inline (Flow)

Sequências flow usam [] e são equivalentes às de bloco. Úteis para listas curtas numa linha. Sequências flow podem atravessar várias linhas, por legibilidade. Diferente do JSON, o YAML proíbe vírgulas finais. Misture sequências flow com mapeamentos em bloco livremente.

yaml
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Mixed: block mapping with flow sequence value
config:
  ports: [80, 443, 8080]
  hosts: [web1, web2, web3]

# Spread across multiple lines (still flow style)
long_list: [
  item1,
  item2,
  item3
]

# NO trailing comma allowed
bad: [1, 2, 3,]   # error

Conteúdo Misto e Heterogêneo

YAML permite conteúdo completamente heterogêneo em sequências e mapeamentos — qualquer item pode ser de qualquer tipo. Essa flexibilidade é poderosa, mas significa que a aplicação precisa validar a estrutura. Use um schema (JSON Schema, Cue etc.) para validação estrita.

yaml
# Sequences can mix types freely
mixed:
  - string
  - 42
  - true
  - null
  - [1, 2, 3]            # nested sequence
  - key: value           # mapping
    another: value2
  - - nested
    - sequence

# Heterogeneous mapping values
config:
  string_val: text
  int_val: 42
  list_val: [a, b, c]
  map_val: {x: 1, y: 2}
  null_val: null
  bool_val: true

# YAML has no schema enforcing uniformity —
# the application must validate structure

Padrões de Indentação de Sequências

Sequências sob uma chave podem ser indentadas (Padrão 1) ou no mesmo nível (Padrão 2, já que - conta como indentação). Ambos são válidos; escolha um e seja consistente. Em sequências de mapeamentos, todas as chaves de um item devem alinhar com a primeira chave depois do -.

yaml
# Pattern 1: sequence indented under key
items:
  - a
  - b

# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b

# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).

# Mapping item alignment — both keys align with first
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# WRONG: misaligned keys cause parse errors
# users:
#   - name: Alice
#    age: 30    # one space off — error
05

Strings Multilinha (Folded e Literal)

Block Scalar Literal (|)

O block scalar literal | preserva cada quebra de linha exatamente como escrita. A indentação (a quantidade além do |) é removida de cada linha. O chomping padrão (clip) mantém uma quebra final. Usado para scripts, código, poesia, ASCII art — qualquer lugar onde quebras literais importam.

yaml
# | preserves newlines as-is
script: |
  #!/bin/bash
  echo "Hello"
  echo "World"

# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n

poem: |
  Roses are red,
  Violets are blue,
  YAML is clean,
  And JSON is too.

# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlines

Block Scalar Folded (>)

O block scalar folded > converte quebras de linha únicas em espaços, unindo linhas em parágrafos. Linhas em branco viram quebras literais. Linhas mais indentadas que o conteúdo do bloco são preservadas literalmente (útil para exemplos de código dentro de prosa).

yaml
# > folds newlines into spaces (paragraphs)
description: >
  This is a long paragraph that
  spans multiple lines in the YAML
  but will be joined into one line
  when parsed.

# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"

# Blank lines preserve a newline
paragraphs: >
  First paragraph here.

  Second paragraph here.

  Third paragraph here.

# More indented lines are preserved literally
example: >
  This is folded.
    This line is more indented — kept literal.

Indicadores de Chomping (+/-)

O chomping controla quebras finais: clip (padrão, sem indicador) mantém uma; strip (-) remove todas; keep (+) preserva todas. O indicador vai logo depois de | ou > (ex.: |-, |+, >-, >+). Strip é útil para strings usadas inline; keep é raro, mas casa exatamente com o fonte.

yaml
# Default (clip): single trailing newline
text: |
  line1
  line2
# Result: "line1\nline2\n"

# Strip (-): remove ALL trailing newlines
text_strip: |-
  line1
  line2
# Result: "line1\nline2"

# Keep (+): keep ALL trailing newlines
text_keep: |+
  line1
  line2


# Result: "line1\nline2\n\n\n"

# Same applies to folded scalars
folded_keep: >+
  folded
  text

Indicador de Indentação

Quando o conteúdo do block scalar começa com espaço em branco, você deve especificar a indentação do conteúdo explicitamente com um dígito (ex.: |2). O dígito indica quantos espaços de indentação pertencem à estrutura vs. ao conteúdo. Combine com chomping: |2-, >4+, etc. Raramente necessário, mas essencial quando é.

yaml
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly

# Without indicator (ambiguous):
# content:
#   indented_line   # is the leading space content or not?

# With explicit indentation indicator (digit after | or >)
literal: |2
    hello
      world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra

# Combined with chomping (order: indent then chomp)
text: |2-
    no trailing newline

# Folded with explicit indent
folded: >4
    paragraph with
    explicit indent

# Most of the time you don't need this — only when
# content legitimately starts with spaces

Strings Multilinha Simples

Escalares simples e entre aspas podem atravessar várias linhas, com quebras dobradas em espaços (parecido com >, mas implícito). Isso é frágil, porque as quebras dependem do contexto e de caracteres especiais. Para qualquer texto multilinha não trivial, prefira block scalars explícitos | (literal) ou > (folded).

yaml
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
  a long message
  on multiple lines
# Result: "this is a long message on multiple lines"

# Quotes are required if the string contains special chars
quoted: "this is also
  a long message
  on multiple lines"
# Result: "this is also a long message on multiple lines"

# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons

# Plain is fragile for multi-line — prefer | or >
safe_literal: |
  Use literal block for
  predictable multi-line text

Escolhendo Fold vs Literal

Regra prática: use | quando as quebras de linha são significativas (scripts, arquivos de config, código); use > quando você quer um fonte multilinha legível, mas um parágrafo unido (descrições, documentação). Use |- para remover a quebra final quando a string é usada inline.

yaml
# Use | (literal) when newlines matter:
script: |
  #!/bin/bash
  set -e
  echo "Step 1"
  echo "Step 2"

config_file: |
  [default]
  region=us-east-1
  output=json

# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
  This service handles user authentication
  and session management. It talks to the
  PostgreSQL database and Redis cache.

# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
  echo hello

# Use plain single-line for short strings
short: hello world
06

Âncoras e Aliases

Definindo Âncoras (&)

&nome define uma âncora num nó (mapeamento, sequência ou escalar). A âncora não muda o valor naquele local — apenas rotula o nó para reuso. Aliases (*nome) referenciam o nó ancorado pelo nome. Âncoras devem ser definidas antes do uso dentro do documento.

yaml
# &name defines an anchor on a node
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
  database: *defaults
  # *defaults is an alias — references the anchored node

# Anchors on scalars
version: &ver "1.0.0"
current: *ver

# Anchors on sequences
colors: &colors
  - red
  - green
  - blue
primary: *colors

Usando Aliases (*)

*nome é um alias que referencia um nó ancorado anteriormente. Aliases compartilham identidade com o original (mesmo objeto na maioria dos parsers). Âncoras/aliases têm escopo de documento — não podem referenciar através de limites de documento ---. Combine com << (merge key) para sobrepor em camadas.

yaml
# Define once, reuse by alias
base: &base
  image: nginx:1.25
  restart: always

web:
  <<: *base
  ports:
    - "80:80"

api:
  <<: *base
  ports:
    - "8080:8080"
  environment:
    - DEBUG=true

# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)

# Aliases can't span documents
# Each document has its own anchor namespace

Escopo de Âncora

Âncoras têm escopo em seu documento e devem ser definidas antes de qualquer alias referenciá-las (sem referências para frente). Múltiplos aliases podem referenciar a mesma âncora. Fazer alias de um alias funciona — resolve transitivamente. Referências entre documentos são um erro.

yaml
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
  key: value
use: *shared   # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared   # ERROR: unknown anchor

# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later      # ERROR
later: &later value

# Multiple aliases to the same anchor are fine
template: &tpl
  timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl

# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b   # resolves to "value"

Sobrescrevendo Valores Ancorados

Um alias (*nome) substitui o nó inteiro — você não pode sobrescrevê-lo parcialmente. Para sobrescrever chaves individuais de um mapeamento ancorado, use a merge key << para mesclar o mapeamento ancorado e depois adicionar ou sobrescrever chaves. Este é o padrão canônico de composição de configuração.

yaml
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  log_level: warn      # override
  host: prod.example.com   # add

# Result:
# production:
#   timeout: 30
#   retries: 3
#   log_level: warn
#   host: prod.example.com

# Without <<, an alias replaces the whole node:
wrong:
  thing: *defaults
  # thing is the FULL defaults mapping — can't override

Âncoras em Sequências

Âncoras podem rotular sequências inteiras, itens individuais de sequência ou mapeamentos dentro de uma sequência. O padrão de merge << é especialmente útil em sequências de registros parecidos (ex.: definições de serviços) para compartilhar campos comuns. Ancore itens individuais com - &nome valor.

yaml
# Anchors work on sequence items too
common: &common
  enabled: true
  log: stdout

services:
  - name: web
    <<: *common
    port: 80
  - name: api
    <<: *common
    port: 8080
  - name: worker
    <<: *common
    queue: jobs

# Anchoring a whole sequence
endpoints: &endpoints
  - /health
  - /metrics
  - /ready

monitoring:
  checks: *endpoints

# Anchoring individual sequence items
list:
  - &first one
  - two
  - *first   # "one" again

Ressalvas das Âncoras

Âncoras têm ressalvas: aliases compartilham identidade (mutar um afeta todas as referências em parsers mutáveis), adicionam carga cognitiva, e a maioria dos serializadores (incluindo saída JSON) os expande para cópias simples. Use âncoras para reuso genuíno (templates, padrões), não para micro-otimização.

yaml
# Caveat 1: shared identity can surprise you
defaults: &defaults
  list: [1, 2, 3]

a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.

# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.

# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.

# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).

# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x   # ERROR

# Prefer anchors for genuine reuse, not micro-optimization.
07

Merge Keys (<<)

Merge Básico (<<)

A merge key << recebe um mapeamento (geralmente um alias) e mescla seus pares chave-valor no mapeamento atual. Chaves definidas explicitamente no mapeamento atual sobrescrevem as mescladas. Este é o padrão canônico de herança de configuração em YAML.

yaml
# << merges a referenced mapping into the current one
defaults: &defaults
  adapter: postgres
  pool: 5
  timeout: 5000

development:
  <<: *defaults
  database: myapp_dev
  host: localhost

production:
  <<: *defaults
  database: myapp_prod
  host: db.example.com
  pool: 20      # override

# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhost

Múltiplos Merges

<< pode mesclar múltiplos mapeamentos passando uma sequência flow de aliases ([*a, *b, *c]). Os merges se aplicam da esquerda para a direita; merges posteriores sobrescrevem os anteriores para chaves duplicadas. Chaves explícitas no mapeamento sempre vencem qualquer chave mesclada. Múltiplas entradas << também são permitidas.

yaml
# << can merge multiple mappings (sequence value)
base: &base
  logging: info
  retries: 3

security: &security
  auth: required
  tls: true

service: &service
  port: 8080
  host: 0.0.0.0

# Merge multiple in one go
production:
  <<: [*base, *security, *service]
  environment: prod
  port: 80        # override service.port

# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.

# You can also have multiple << entries:
combined:
  <<: *base
  <<: *security
  custom: value

Override e Precedência

Precedência de merge: chaves explícitas no mapeamento sempre vencem. Entre mapeamentos mesclados, os posteriores na sequência sobrescrevem os anteriores para a mesma chave. Use isso para sobrepor de forma limpa: padrões → específicos de papel → específicos de instância.

yaml
# Explicit keys override merged keys
template: &template
  port: 8080
  log: info
  timeout: 30

instance:
  <<: *template
  port: 9090        # overrides template.port
  log: debug        # overrides template.log
  host: example.com # added

# Final: {port: 9090, log: debug, timeout: 30, host: example.com}

# Precedence: explicit > later merge > earlier merge
a: &a
  k: from_a
  x: 1
b: &b
  k: from_b
  y: 2

result:
  <<: [*a, *b]
  k: explicit   # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}

Padrão de Merge com Âncoras

O padrão de merge+âncora é o pão e a manteiga do Docker Compose e de arquivos de config semelhantes: defina uma âncora de padrões, então cada serviço a mescla e sobrescreve campos individuais. Isso mantém as configs DRY sem sacrificar a personalização por serviço.

yaml
# Common pattern: anchor templates, merge + override
defaults: &defaults
  image: nginx:1.25
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *defaults
    ports: ["80:80"]
  api:
    <<: *defaults
    image: node:20      # override
    ports: ["8080:8080"]
    environment:
      NODE_ENV: production
  worker:
    <<: *defaults
    image: worker:latest
    command: ["./run.sh"]

# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.

Limitações do Merge

A merge key << só funciona para mapeamentos — sequências e escalares não podem ser mesclados. O merge é raso: um mapeamento aninhado no nó atual SUBSTITUI inteiramente o mesclado (sem deep merge). Para merge profundo, reestruture os dados ou faça no código da aplicação.

yaml
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]

# This does NOT merge list items:
combined:
  <<: *list      # WRONG: *list is a sequence, not a mapping
  extra: value   # parse error or unexpected behavior

# Deep merge is NOT supported
parent: &parent
  nested:
    a: 1
    b: 2

child:
  <<: *parent
  nested:
    c: 3   # REPLACES parent.nested entirely
# Result: {nested: {c: 3}}  — NOT {nested: {a:1, b:2, c:3}}

# To deep-merge, you must do it in application code
# or restructure the data.

Status e Obsolescência da Merge Key

A merge key << era uma extensão do YAML 1.1, removida da especificação central do YAML 1.2. Na prática, a maioria dos parsers ainda a suporta (PyYAML, js-yaml, ruamel, SnakeYAML), mas parsers 1.2 estritos a rejeitam. Use-a hoje, mas saiba que é não padrão; para formatos novos, considere linguagens de config com herança real (Cue, Jsonnet, Dhall).

yaml
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.

# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports

# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
#   <<: *template    # ERROR in strict 1.2

# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
#   or a config language with proper inheritance
#   (e.g. Dhall, Cue, Jsonnet)

# Alternative without <<:
# just duplicate or use application-level templating
08

Tags de Tipo

Tags Embutidas

Tags embutidas usam o prefixo !! (abreviação de tag:yaml.org,2002:). Elas forçam um tipo específico, independentemente da inferência de schema. Tags comuns: !!str, !!int, !!float, !!bool, !!null, !!binary, !!map, !!seq, !!omap, !!set, !!timestamp. Úteis quando a inferência chutaria errado.

yaml
# YAML tags use !! prefix for built-in types
# (the long form is tag:yaml.org,2002:)

# Common built-in tags
str: !!str hello
int: !!int 42
float: !!float 3.14
bool: !!bool true
null: !!null null
binary: !!binary "SGVsbG8="
map: !!map {a: 1}
seq: !!seq [1, 2]
omap: !!omap
  - a: 1
  - b: 2
set: !!set
  ? item1
  ? item2
timestamp: !!timestamp 2024-01-01T00:00:00Z
merge: !!merge "<<"   # the merge key tag

# Tags force a specific type regardless of inference
forced_str: !!str 42        # "42" string
forced_int: !!int "42"      # 42 integer
forced_bool: !!bool "yes"   # true

Forçando Tipos

Tags forçam um tipo específico, sobrescrevendo a inferência de schema. O uso mais comum é !!str para impedir que strings que pareçam números/booleanos/datas sejam convertidas. !!int e !!float podem analisar strings numéricas. Tags são essenciais quando a aplicação hospedeira precisa de um tipo específico.

yaml
# Without tags, type depends on schema inference
value: 42          # integer (Core schema)
value: "42"        # string (quoted)
value: !!str 42    # string (forced by tag)

# Common forcing scenarios
version: !!str 1.0       # "1.0" string, not float
phone: !!str 5551234     # string, not int
answer: !!str yes        # string, not bool (1.1)
region: !!str no         # string "no", not False (1.1)

# Force numeric parsing from strings
count: !!int "100"       # 100 integer
ratio: !!float "0.5"     # 0.5 float

# Force bool from strings
enabled: !!bool "yes"    # true
enabled: !!bool "off"    # false

# Force null
empty: !!null ""         # null
empty: !!null "~"        # null

Tags Personalizadas

Tags personalizadas usam um único prefixo ! e são definidas pela aplicação. A aplicação hospedeira deve registrar um construtor para cada tag. Loaders seguros (recomendados) rejeitam tags desconhecidas por padrão — você precisa optar explicitamente. Tags específicas de biblioteca (como python/object do PyYAML) podem ser perigosas e são desativadas por loaders seguros.

yaml
# Application-specific tags use ! prefix
# The application's YAML loader must handle them

# Custom tag (application-defined)
person: !person
  name: Alice
  age: 30

# Tag with arguments
color: !color rgb(255, 0, 0)
point: !point [10, 20]

# Library-specific tags (PyYAML example)
# python/object/apply:module.func args
sorted_set: !!python/object/apply:sorted
  args:
    - [3, 1, 2]

# Ruby-specific (Psych)
# !ruby/object:ClassName

# Custom tags require custom constructors in code.
# Unknown tags usually cause errors in safe loaders.

Tags Locais e Verbatim

!prefixo é para tags locais (definidas pela aplicação), !! é abreviação das tags globais do yaml.org, !<uri> é verbatim (sem resolução), e !prefixo!curto usa prefixos declarados com %TAG por brevidade. Tags locais são as mais comuns; tags verbatim importam para schemas entre ferramentas.

yaml
# ! prefix — local tag (application-specific, no URI)
data: !myapp/data
  value: 42

# !! prefix — global built-in tag (resolved to yaml.org)
str: !!str hello

# !<full-uri> — verbatim tag (exact URI, no resolution)
binary: !<tag:example.com,2024:binary> "data"

# !tag!short — tag with prefix (resolved via %TAG directive)
%TAG !e! tag:example.com,2024:
data: !e!custom value
# resolves to tag:example.com,2024:custom

# %TAG directives declare prefixes
%TAG !yaml! tag:yaml.org,2002:
value: !yaml!str 42   # same as !!str

# Local tags are most common in app-specific YAML
# Verbatim tags are useful for cross-tool interoperability

Resolução de Tags

A resolução de tags depende do schema. Failsafe (mínimo) trata tudo como string, a menos que haja tag. O schema JSON adiciona int/float/bool/null. O schema Core (padrão do YAML 1.2) estende o JSON com casamento mais leniente. Tags explícitas (!!) sempre sobrescrevem a resolução do schema.

yaml
# Tags are resolved by the schema (Core, JSON, Failsafe)
# Without explicit tags, the schema infers types

# Failsafe schema — only str, map, seq (no inference)
# Everything is a string unless tagged
failsafe_value: 42       # str "42"
failsafe_tagged: !!int 42  # int 42

# JSON schema — str, int, float, bool, null, map, seq
json_value: 42           # int
json_str: "42"           # str

# Core schema (default for YAML 1.2) — like JSON but
# with more lenient parsing (yes/no not bool, etc.)
core_value: 42           # int
core_bool: true          # bool
core_str: hello          # str

# Explicit tags override schema resolution
forced: !!str true       # str "true" (even in Core)

Tags Específicas da Aplicação

Tags específicas da aplicação permitem embutir objetos de domínio (Money, DateRange etc.) em YAML. O loader deve registrar um construtor para cada tag. Sempre use safe_loaders que rejeitam tags desconhecidas por padrão — nunca deixe YAML não confiável invocar construtores arbitrários (uma vulnerabilidade clássica de desserialização).

yaml
# Define your own tags for domain objects
# Example: a config loader for a custom app

# Tag a node as a "Money" object
price: !money "USD 19.99"

# Tag a node as a "DateRange"
range: !dateRange
  start: 2024-01-01
  end: 2024-12-31

# Tag nodes for custom parsing/validation
settings: !strict
  host: localhost
  port: 8080

# PyYAML example: register a constructor
# class MoneyLoader:
#     def __init__(self, value):
#         self.currency, self.amount = value.split()
#         self.amount = float(self.amount)
#
# yaml.add_constructor('!money', lambda l, n:
#     MoneyLoader(l.construct_scalar(n)))

# Safe loaders reject unknown tags — opt-in explicitly
# to avoid processing untrusted input with side effects.
09

Marcadores e Diretivas de Documento

Documento Único

Um único documento YAML funciona bem sem nenhum marcador. Um --- inicial é uma convenção para sinalizar 'isto é YAML' e desambiguar de texto simples. O marcador de fim ... é opcional e raramente usado em arquivos de documento único.

yaml
# A single YAML document needs no markers
key: value
list:
  - a
  - b

# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value

# The trailing ... (end marker) is optional
# for a single document
key: value
...

Múltiplos Documentos (Stream)

Um stream YAML é uma sequência de documentos separados por ---. Cada documento é analisado independentemente. Streams são comuns no Kubernetes (múltiplos objetos por arquivo), geradores de sites estáticos e arquivos de log. Use load_all() ou equivalente no seu parser para iterar documentos.

yaml
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3

# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
#   for doc in yaml.safe_load_all(stream):
#       print(doc)

# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelines

Marcador de Fim (...)

O marcador ... termina explicitamente um documento. É opcional na maioria dos casos, mas útil quando o conteúdo pode ser ambíguo (ex.: um block literal contendo ---). Também sinaliza fim de documento a parsers de streaming. Raro em YAML escrito à mão, comum em saída programática.

yaml
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end

# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
  Some content
  ---
  that looks like a separator
...
---
next: document

# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)

# ... is also useful in programmatic output to flush

Diretivas

Diretivas aparecem antes do conteúdo do documento e configuram o parser. %YAML define a versão; %TAG declara atalhos de prefixo de tags. Diretivas têm escopo de documento — valem só para o próximo documento. A maioria dos arquivos de config omite diretivas e confia nos padrões do parser (geralmente bimodal 1.1 ou 1.2).

yaml
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value

# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value

# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello

# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.

Exemplos de Stream de Documentos

Streams de documentos são amplamente usados. O Kubernetes os usa para agrupar múltiplos objetos (Namespace, Deployment, Service) num arquivo. Templates Helm, logs de CI e geradores de sites estáticos (front matter + conteúdo) também usam streams. Cada documento é independente e pode ter as próprias diretivas.

yaml
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: production
spec:
  ports:
    - port: 80

# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + body

Armadilhas de Fronteira

Uma linha começando com --- na coluna 0 é sempre um separador de documento (fora de block scalars). Dentro de block scalars (|, >), --- é conteúdo literal. Para incluir --- na coluna 0 num valor, indente o bloco ou termine o documento com ... primeiro. Um --- com conteúdo na mesma linha é marcador de início de documento, não separador.

yaml
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:

---
script: |
  echo hello
  ---  # this is INSIDE the block scalar — safe
next: value

# But this is NOT safe:
---
content: |
  line1
---
mistaken: this is a NEW document, not part of content!

# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.

# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.

# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value   # this is one document
10

Estilo Flow

Sequências Flow

Sequências flow usam [ ] e se comportam como arrays JSON. Espaços e quebras internas são flexíveis. Diferente do JSON, vírgulas finais NÃO são permitidas. Útil para listas curtas e densas. Coloque aspas em itens com caracteres especiais (vírgulas, colchetes, dois-pontos).

yaml
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Empty
empty: []

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Multi-line flow sequence (whitespace is flexible)
long: [
  alpha,
  beta,
  gamma
]

# Quoting inside flow
mixed: ["hello", 'world', 42, true]

# NO trailing comma
bad: [1, 2, 3,]   # parse error

Mapeamentos Flow

Mapeamentos flow usam { } e se comportam como objetos JSON. Chaves podem ter aspas quando contêm caracteres especiais. Espaços são flexíveis. Vírgulas finais são proibidas (diferente do JSON). Use mapeamentos flow para dados curtos e densos; o estilo block é mais legível para estruturas maiores.

yaml
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Empty mapping
empty: {}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}

# Multi-line flow mapping
config: {
  host: localhost,
  port: 8080,
  debug: true
}

# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}

# NO trailing comma
bad: {a: 1, b: 2,}   # parse error

Mistura de Flow e Block

Estilos flow e block podem ser misturados livremente num documento. A regra pragmática: use block para elementos estruturais (melhor legibilidade com indentação) e flow para valores inline curtos (listas de escalares, maps pequenos). Evite flow profundamente aninhado — fica ilegível rápido.

yaml
# Mix flow and block styles freely
config:
  name: myapp
  ports: [80, 443]        # flow sequence in block mapping
  endpoints: {api: /v1, web: /}  # flow mapping in block

# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]

# Flow at top level
[top, level, flow]

# Block at top level
- block
- sequence

# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadable

Flow Aninhado

O estilo flow pode aninhar arbitrariamente, mas cada nível adiciona colchetes/chaves que ficam difíceis de ler. Depois de 1-2 níveis de aninhamento, troque para block por legibilidade. O equivalente em block de um flow profundamente aninhado quase sempre é mais claro para mantenedores humanos.

yaml
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}

# Equivalent block:
# data:
#   users:
#     - name: Alice
#       tags:
#         - a
#         - b
#     - name: Bob

# Multi-line nested flow (rare but valid)
matrix: {
  rows: [
    [1, 2, 3],
    [4, 5, 6]
  ],
  cols: 3
}

# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".

Quando Usar Estilo Flow

Use flow para listas curtas de escalares, maps de consulta pequenos, registros de linha única e saída compatível com JSON. Evite flow para listas longas (difíceis de escanear), estruturas profundamente aninhadas (parede de colchetes) ou qualquer coisa que precise de comentários inline. Na dúvida, prefira block pela legibilidade.

yaml
# Good uses of flow style:

# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]

# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}

# 3. Single-line records in a sequence
coordinates:
  - {x: 1, y: 2}
  - {x: 3, y: 4}
  - {x: 5, y: 6}

# 4. JSON-compatible output (flow is JSON-compatible)

# Bad uses of flow style:

# 1. Long lists (use block)
#   ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...]  # hard to read

# 2. Deeply nested (use block)
#   {a: {b: {c: {d: {e: value}}}}}  # unreadable

# 3. Anything with comments (flow doesn't allow inline comments well)

Ressalvas do Estilo Flow

O estilo flow tem ressalvas: caracteres especiais (vírgulas, dois-pontos, colchetes) precisam de aspas; sem vírgulas finais; comentários são desajeitados; sem block scalars | ou > (use \n em strings entre aspas duplas); e mudanças de linha única são mais difíceis de comparar. O estilo block é mais amigável para config versionada.

yaml
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"]   # commas and colons need quoting
block:
  - a
  - b
  - c,d      # no quotes needed in block style
  - d:e      # no quotes needed in block style

# Caveat 2: no trailing commas
bad: [1, 2, 3,]   # error

# Caveat 3: comments are awkward in flow
config: {
  host: localhost,  # comment allowed but clunky
  port: 8080
}

# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"

# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)
11

Conversão YAML e JSON

JSON é YAML Válido

YAML 1.2 foi projetado para que JSON seja um subconjunto estrito — qualquer documento JSON é YAML válido. A maioria dos parsers YAML lê JSON sem problemas. O inverso não vale: recursos do YAML como comentários, âncoras, streams multidocumento e block scalars não são JSON válido.

yaml
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML

# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# So is this multi-line JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["a", "b"]
}

# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string)  # works
# JS:     YAML.load(json_string)       # works
# Go:     yaml.Unmarshal(json_bytes, &v)  # works (yaml.v3)

# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSON

Representações Equivalentes

JSON, YAML block e YAML flow podem representar os mesmos dados. JSON é o mais portátil (toda linguagem tem parser JSON). YAML block é o mais legível para humanos. YAML flow é um meio-termo compacto. Escolha conforme o público: ferramentas (JSON) vs humanos (YAML block).

yaml
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# YAML block:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}

# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline data

Conversão de JSON para YAML

Converta JSON para YAML analisando o JSON e gerando YAML com default_flow_style=False (estilo block). As aspas obrigatórias do JSON são descartadas onde o YAML não precisa delas. Cuidado com chaves que parecem números/booleanos — podem precisar de aspas no YAML para preservar o tipo string.

yaml
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)

# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}

# Output YAML:
# server:
#   host: localhost
#   port: 8080
# debug: true

# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preserved

Conversão de YAML para JSON

Converta YAML para JSON analisando e serializando para JSON. Ressalvas: comentários e tags se perdem; âncoras são expandidas para cópias simples; streams multidocumento precisam virar um array JSON; datas YAML podem virar strings. Ferramentas como yq facilitam isso na linha de comando.

yaml
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)

# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)

# Command-line tools:
# yq -o=json '.config' file.yaml        # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'

# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)

Subconjunto Compatível com JSON

O subconjunto do YAML compatível com JSON evita comentários, âncoras, múltiplos docs, tags, block scalars e strings simples que pareçam outros tipos. Manter-se nesse subconjunto garante idas e voltas limpas para JSON. Útil quando consumidores YAML e JSON leem os mesmos dados, ou quando a preservação estrita de tipos importa.

yaml
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:

# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types

# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}

# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.

# Many YAML dumpers have a "json-compatible" mode.

Considerações de Ida e Volta

A ida e volta do YAML (analisar e gerar) costuma perder comentários, nomes de âncoras, ordem de chaves, estilo de aspas e formatação. ruamel.yaml (Python) tem um modo round-trip que preserva comentários e ordem. Para config editada por humanos, nunca sobrescreva cegamente com a saída do dumper — faça diff cuidadoso primeiro.

yaml
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives

# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting

# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
#   without diffing carefully
12

Schemas YAML

Schema Failsafe

O schema Failsafe é o mais conservador — reconhece apenas str, map e seq. Cada um dos escalares são strings, a menos que tenham tag explícita. Útil para entrada não confiável (sem surpresas de conversão implícita) ou como base para schemas personalizados. A maioria dos loaders de produção usa um schema um pouco mais rico.

yaml
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string

# Under Failsafe:
value: 42           # str "42" (NOT int)
flag: true          # str "true" (NOT bool)
empty: null         # str "null" (NOT null)
date: 2024-01-01    # str "2024-01-01" (NOT date)

# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null

# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas

# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.

Schema JSON

O schema JSON casa exatamente com o sistema de tipos do JSON: str, int, float, bool, null, map, seq. É mais estrito que o schema Core — sem literais octais/binários, sem separadores underscore, só true/false como booleanos, sem inferência de data. Use-o para interop com JSON ou comportamento de tipo estrito.

yaml
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq

# Under JSON schema:
int: 42             # int
float: 3.14         # float
str: hello          # str
bool: true          # bool
null_val: null      # null
list: [1, 2, 3]     # seq
map: {a: 1}         # map

# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference

# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semantics

Schema Core

O schema Core é o padrão do YAML 1.2. Estende o JSON com análise leniente: hex (0x), octal (0o), binário (0b), underscores em números, floats .inf/.nan. Booleanos são apenas true/false (não yes/no). Datas são strings (sem inferência). A maioria dos parsers modernos assume Core ou uma variante compatível com 1.1.

yaml
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution

# Under Core schema:
int: 42             # int
neg: -17            # int
hex: 0xFF           # int (255)
oct: 0o17           # int (15)  [YAML 1.2 syntax]
bin: 0b1010         # int (10)
float: 3.14         # float
exp: 1.0e+3         # float
inf: .inf           # float
nan: .nan           # float
bool: true          # bool (only true/false, not yes/no)
null: null          # null (also ~, empty)
str: hello          # str
date: 2024-01-01    # str (Core does NOT infer dates)

# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)

# Most modern parsers default to Core or close to it.

YAML 1.1 vs 1.2

YAML 1.1 (padrão do PyYAML) trata yes/no/on/off como booleanos e números com 0 inicial como octal — fontes famosas de bugs (Noruega 'no' → false). YAML 1.2 (especificação atual) restringe booleanos a true/false e usa 0o para octal. Sempre verifique o padrão do seu parser e coloque aspas em strings ambíguas.

yaml
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes       # true (yes/no/on/off are booleans)
octal_1_1: 017      # 15 (leading 0 = octal)
sexagesimal: 1:30   # 90 (base-60!) - obscure feature

# YAML 1.2 (current spec)
bool_1_2: yes       # str "yes" (only true/false are bool)
octal_1_2: 0o17     # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"

# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2

# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish

# Always check your parser's default schema!

Diferenças de Resolução de Tipo

A resolução de tipos difere entre parsers YAML 1.1 e 1.2: yes/no/on/off, números com zero inicial e literais sexagesimais são analisados de forma diferente. Mitigue colocando aspas em strings ambíguas, fixando a versão com %YAML, usando tags explícitas e testando contra cada um dos parsers alvo.

yaml
# Same YAML, different parsers, different types:
value: yes

# PyYAML (1.1):        True (bool)
# js-yaml (1.1):       true (bool)
# ruamel (1.2):        "yes" (str)
# Go yaml.v3 (1.2):    "yes" (str)
# Strict 1.2:          "yes" (str)

value: 010

# PyYAML (1.1):        8 (int, octal)
# ruamel (1.2):        "010" (str)
# Go yaml.v3 (1.2):    "010" (str)

value: 1.0

# All:                 1.0 (float) - consistent

value: true

# All:                 true (bool) - consistent

# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsers

Escolhendo um Schema

Escolha o schema pelo caso de uso: 1.2 Core para projetos novos (previsível), 1.1 para interop com PyYAML (ou coloque aspas em strings ambíguas), Failsafe/JSON para entrada não confiável, schema JSON para interop com JSON. Para arquivos de config, 1.2 Core mais aspas em strings ambíguas ("no", "010" etc.) é a combinação mais segura.

yaml
# Recommendations for choosing a schema:

# 1. For NEW projects: use YAML 1.2 Core schema
#    - More predictable (no yes/no surprises)
#    - Modern parsers support it
#    - ruamel.yaml, Go yaml.v3 default to it

# 2. For INTEROP with existing PyYAML code:
#    - Either accept 1.1 semantics
#    - Or use ruamel.yaml with 1.2 + preserve 1.1 features
#    - Quote all ambiguous strings explicitly

# 3. For UNTRUSTED input: use Failsafe or JSON schema
#    - No implicit type coercion
#    - Smaller attack surface
#    - Predictable behavior

# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
#    - "no", "yes", "on", "off", "010", "1.0" should be quoted
#    - Document your schema choice
#    - Lint with yamllint

# 5. For JSON INTEROP: use JSON schema
#    - Same types as JSON
#    - Round-trips cleanly
13

Lint e Validação YAML

yamllint

yamllint é o linter YAML padrão (Python). Ele captura erros de sintaxe, problemas de indentação, espaços finais, marcadores de documento ausentes e mais. Use no CI e em hooks de pre-commit para capturar problemas de YAML cedo. O modo estrito (-s) trata avisos como erros.

yaml
# yamllint is the standard YAML linter
# Install: pip install yamllint

# Lint a file
# yamllint config.yaml

# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml

# Output example:
# config.yaml
#   3:4       error    mapping values are not allowed here
#   5:1       error    syntax error: found character '	' that cannot start any token
#   8:3       warning  missing document start "---"
#   12:5      warning  comment is not indented like content

# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml

# Lint a directory (recursive)
# yamllint -d path/to/dir

# Read from stdin
# cat config.yaml | yamllint -

Configuração do Lint

Configure o yamllint com .yamllint.yml. Estenda um perfil (default ou strict) e depois sobrescreva regras individuais: indentação, comprimento de linha, estilo de aspas, comentários, espaços finais, marcadores de documento. Ajuste para o estilo da sua equipe. Rode no CI para impor de forma consistente.

yaml
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config

# Use a built-in profile
extends: default

# Or use a stricter profile
# extends: strict

# Override specific rules
rules:
  # Require document start marker
  document-start: disable
  # Enforce 2-space indentation
  indentation:
    spaces: 2
    indent-sequences: true
  # Max line length
  line-length:
    max: 120
    allow-non-breakable-words: true
  # Disallow trailing spaces
  trailing-spaces: enable
  # Require consistent quoting
  quoted-strings:
    quote-type: double
    required: only-when-needed
  # Disallow comments without space before #
  comments:
    require-starting-space: true
    min-spaces-from-content: 1

Erros de Sintaxe Comuns

Erros YAML comuns: tabs para indentação (só espaços permitidos), dois-pontos sem espaço depois, strings sem aspas com dois-pontos (analisadas como mapeamentos), vírgulas finais em estilo flow, indentação inconsistente e chaves duplicadas. Um linter captura tudo automaticamente.

yaml
# Error: tab characters for indentation
# bad:
# 	key: value   <- tab not allowed
# Fix: use spaces only

# Error: colon without space
# bad:  key:value
# good: key: value

# Error: unquoted special characters
# bad:  url: http://example.com:8080   <- parsed as mapping
# good: url: "http://example.com:8080"

# Error: trailing comma in flow
# bad:  list: [1, 2, 3,]
# good: list: [1, 2, 3]

# Error: inconsistent indentation
# bad:
#   key1: value
#    key2: value   <- one extra space
# good:
#   key1: value
#   key2: value

# Error: duplicate keys (some parsers warn)
# bad:
#   key: first
#   key: second
# good: rename one

Erros de Tab vs Espaço

Tabs são estritamente proibidos para indentação estrutural YAML — a causa nº 1 de erros de análise. Tabs dentro de valores de string (block scalars, strings com aspas) estão bem. Configure seu editor para usar espaços (expandtab) em arquivos YAML. Detecte linhas problemáticas com grep -P '\t'.

yaml
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.

# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"

# Tabs are allowed INSIDE string values:
script: |
  #!/bin/bash
  if [ -f file ]; then   # this is fine (literal content)
  \techo found           # \t inside block scalar is OK

# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx

# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2

# Detect tabs:
# grep -P '\t' file.yaml   (finds offending lines)

Detecção de Chaves Duplicadas

Chaves duplicadas num mapeamento são desencorajadas e fonte comum de bugs (sobrescrita silenciosa, última vence). O yamllint as detecta com a regra key-duplicates (habilitada por padrão). Causas comuns: erros de copiar/colar e má resolução de conflitos de merge. Sempre lint no CI para capturá-las cedo.

yaml
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).

config:
  host: localhost
  port: 8080
  host: prod.example.com   # silent override!

# yamllint catches these:
#   4:3  error  duplication of key "host" in mapping

# Enable in .yamllint.yml:
# rules:
#   key-duplicates: enable

# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)

# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.

Validação de Schema

Valide a estrutura YAML com JSON Schema (funciona porque YAML é um superconjunto do JSON). Para Kubernetes, use kubeval ou kubectl --dry-run. Para configuração geral, use yamllint (sintaxe/estilo) mais jsonschema (estrutura) ou Cue (linguagem de schema). Integre a validação em hooks de pre-commit e CI.

yaml
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)

# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)

# Tools for Kubernetes YAML:
# kubeval            - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest           - policy-based validation (OPA)

# Tools for general YAML:
# yamllint           - syntax + style
# jsonschema-cli     - JSON Schema validation
# cue                - schema + validation language
# dataladen          - config validation

# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.32.0
#     hooks:
#       - id: yamllint
#         args: [-s]
14

YAML do Docker Compose

Definição de Serviço

Arquivos do Docker Compose definem apps multi-contêiner. As chaves de topo são version, services, volumes, networks, configs, secrets. Cada serviço define image/build, ports, volumes, environment, depends_on, política de restart. Volumes declarados no topo são nomeados e persistidos.

yaml
# docker-compose.yml — multi-container apps
version: "3.9"   # compose file format version

services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped
    depends_on:
      - api

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - DB_URL=postgres://db:5432/app
    ports:
      - "8080:8080"
    restart: always

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always

volumes:
  db_data:

Volumes e Networks

Volumes do Compose são bind mounts (host:contêiner), nomeados (declarados no volumes de topo) ou anônimos. O sufixo :ro torna as montagens somente leitura. Networks isolam serviços; internal: true bloqueia acesso externo. Volumes nomeados persistem dados entre recriações de contêiner.

yaml
services:
  web:
    image: nginx
    volumes:
      # Bind mount: host:container
      - ./html:/usr/share/nginx/html:ro
      # Named volume: name:container
      - shared_data:/data
      # Anonymous volume
      - /tmp/cache
    networks:
      - frontend
      - backend

  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db_data:
    driver: local
  shared_data:
    driver: nfs
    driver_opts:
      type: nfs
      device: ":/path/to/share"

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

Variáveis de Ambiente

O Compose suporta três estilos de variável de ambiente: lista (KEY=value), map (KEY: value) e env_file. ${VAR} é interpolado do shell do host ou do arquivo .env na hora da análise; ${VAR:-default} fornece padrões. Use $$ para escapar um $ literal. O arquivo .env na raiz do projeto é carregado automaticamente.

yaml
services:
  api:
    image: myapi
    # Method 1: list of KEY=value
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    # Method 2: map (cleaner)
    environment:
      NODE_ENV: production
      LOG_LEVEL: info
    # Method 3: file
    env_file:
      - .env
      - .env.production
    # Interpolation from host environment
    environment:
      - API_KEY=${API_KEY}     # from shell
      - PORT=${PORT:-8080}      # default 8080

# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...

# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5   # produces price_$5

Depends, Healthchecks e Restart

depends_on com condition: service_healthy espera o healthcheck da dependência passar antes de iniciar. Healthchecks usam test (CMD ou CMD-SHELL), interval, timeout, retries, start_period. Políticas de restart: no, always, unless-stopped (sobrevive a reinicializações, mas respeita parada manual), on-failure.

yaml
services:
  api:
    image: myapi
    depends_on:
      db:
        condition: service_healthy   # wait for db healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

# restart policies:
# no              - never restart (default)
# always          - always restart on stop
# unless-stopped  - restart unless manually stopped
# on-failure      - restart only on non-zero exit

Arquivos de Override

O Compose mescla arquivos de override sobre a base. docker-compose.override.yml é aplicado automaticamente. Mapeamentos recebem deep merge (overrides vencem); sequências geralmente são substituídas (não anexadas) — cuidado com ports/volumes. Use flags -f para especificar a ordem explícita de arquivos para configs por ambiente.

yaml
# docker-compose.yml — base
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - ENV=base

# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
  web:
    ports:
      - "8080:80"      # overrides "80:80"
    environment:
      - DEBUG=true     # added
      - ENV=override   # overrides ENV=base
    volumes:
      - ./dev.conf:/etc/nginx/conf.d/default.conf

# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up

# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
#   ports/depends_on/volumes are exceptions in some versions

# Use -f to specify explicit file order

Profiles e Recursos do Compose

Profiles permitem ativar serviços (ex.: debug, test, ci) com a flag --profile. Outros recursos da v3: init (tratamento correto de sinais no PID 1), extends (herdar de outro serviço), configs e secrets (montados como arquivos), deploy (posicionamento/réplicas/recursos do Swarm). Profiles são ótimos para manter um arquivo compose para múltiplos ambientes.

yaml
# Profiles — opt-in services
services:
  web:
    image: nginx
    # no profile: always started

  debug:
    image: busybox
    profiles: ["debug"]   # only with --profile debug

  loadtest:
    image: locust
    profiles: ["test", "ci"]

# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up

# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1

services:
  worker:
    image: worker
    init: true   # proper signal handling
    extends:
      service: base   # inherit fields
    configs:
      - config1
    secrets:
      - api_key

configs:
  config1:
    file: ./config.toml
secrets:
  api_key:
    file: ./api_key.txt
15

YAML do Kubernetes

Estrutura de Objeto

Cada objeto Kubernetes tem apiVersion, kind, metadata e spec. apiVersion é grupo/versão (ex.: apps/v1, v1 para o núcleo). metadata inclui name, namespace, labels, annotations. spec é o estado desejado — o Kubernetes trabalha para que a realidade case com o spec. status é definido pelo sistema.

yaml
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1        # API group + version
kind: Deployment           # object type
metadata:                  # identity
  name: my-app
  namespace: production
  labels:
    app: my-app
    tier: backend
  annotations:
    deployment.kubernetes.io/revision: "1"
spec:                      # desired state
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080

# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)

Labels e Selectors

Labels identificam e agrupam objetos; selectors consultam por labels. Seletores por igualdade (chave=valor) e por conjunto (In, NotIn, Exists, DoesNotExist) são ambos suportados. Annotations guardam metadados não identificadores (descrições, contato, config de ferramentas). Labels são para seleção; annotations, para informação adicional.

yaml
# Labels — identify and group objects
metadata:
  labels:
    app: my-app
    tier: backend
    env: production
    version: "1.0"

# Selectors — query objects by labels
# Equality-based
selector:
  matchLabels:
    app: my-app
    env: production

# Set-based
selector:
  matchExpressions:
    - {key: tier, operator: In, values: [backend, api]}
    - {key: env, operator: NotIn, values: [dev]}
    - {key: version, operator: Exists}

# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production

# Annotations — non-identifying metadata
metadata:
  annotations:
    description: "My app deployment"
    contact: "[email protected]"

Spec de Pod

O spec de um Pod define contêineres, suas imagens, portas, variáveis de ambiente (literais ou de secrets/configmaps), recursos (requests/limits), probes (readiness/liveness), volumes e volumeMounts. Pods são a menor unidade implantável, mas você normalmente os cria via Deployments, não diretamente.

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: app
      image: my-app:1.0
      ports:
        - containerPort: 8080
          name: http
      env:
        - name: LOG_LEVEL
          value: info
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: secret-key
      resources:
        requests: {cpu: 100m, memory: 128Mi}
        limits: {cpu: 500m, memory: 512Mi}
      readinessProbe:
        httpGet: {path: /health, port: 8080}
        initialDelaySeconds: 5
        periodSeconds: 10
      volumeMounts:
        - name: config
          mountPath: /etc/config
  volumes:
    - name: config
      configMap:
        name: app-config
  restartPolicy: Always

Deployment

Um Deployment gerencia ReplicaSets e Pods. spec.replicas define a contagem desejada. strategy.type pode ser RollingUpdate (padrão, controlado por maxSurge/maxUnavailable) ou Recreate. O template de pod (spec.template) define como os pods são criados. Gerencie rollouts com kubectl rollout status/undo/history.

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          resources:
            requests: {cpu: 100m, memory: 128Mi}
            limits: {cpu: 500m, memory: 512Mi}
          readinessProbe:
            httpGet: {path: /ready, port: 8080}
  # Rollback / history
  # kubectl rollout status deployment/my-app
  # kubectl rollout undo deployment/my-app
  # kubectl rollout history deployment/my-app

Service

Um Service expõe Pods como serviço de rede. O tipo ClusterIP (padrão) é só interno; NodePort expõe em cada nó; LoadBalancer provisiona um LB na nuvem; ExternalName é um CNAME DNS. O selector roteia tráfego para pods que casem. ports mapeia a porta do serviço para o targetPort do contêiner (número ou nome).

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: ClusterIP      # ClusterIP (default), NodePort, LoadBalancer, ExternalName
  selector:
    app: my-app        # routes to pods with these labels
  ports:
    - name: http
      port: 80         # service port
      targetPort: 8080 # container port (or named port)
      protocol: TCP
    - name: https
      port: 443
      targetPort: 8443

# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service

# Service types:
# ClusterIP    - internal cluster IP (default)
# NodePort     - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)

ConfigMap e Secret

ConfigMaps guardam configuração não sensível (strings ou arquivos); Secrets guardam dados sensíveis (codificados em base64 em data, ou em texto em stringData). Ambos são consumidos via variáveis de ambiente (valueFrom) ou montados como volumes. Secrets NÃO são criptografados por padrão — habilite criptografia em repouso e restrinja o acesso por RBAC.

yaml
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  log_level: info
  max_connections: "100"
  config.yaml: |
    server:
      host: 0.0.0.0
      port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  # base64-encoded values
  api_key: c2VjcmV0LWtleS0xMjM=   # echo -n 'secret-key-123' | base64
  db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
#   api_key: secret-key-123

# Consumed by pods:
# env:
#   - name: API_KEY
#     valueFrom:
#       secretKeyRef:
#         name: app-secrets
#         key: api_key
# volumes:
#   - name: config
#     configMap:
#       name: app-config
16

Configuração de CI/CD (GitHub Actions e GitLab CI)

Workflow do GitHub Actions

Workflows do GitHub Actions vivem em .github/workflows/. on: são gatilhos (push, PR, schedule, workflow_dispatch). jobs contêm runs-on + steps. uses: referencia actions, run: executa shell. Expressões usam a sintaxe ${{ }} — precisam ser escapadas como \${{ }} dentro de literais de template YAML.

yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: npm run build
        env:
          NODE_ENV: production

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint

# ${{ }} is GitHub Actions expression syntax
# MUST be escaped as ${{ }} in YAML template literals
# (here we use literal text, no escaping needed)

Pipeline do GitLab CI

GitLab CI vive em .gitlab-ci.yml. stages definem a ordem do pipeline. Jobs têm stage, image, script e muitas opções (only/except, rules, when, artifacts, environment). Variáveis usam sintaxe $VAR (sem escape necessário em block scalars YAML). when: manual exige um clique para implantar.

yaml
# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  NODE_ENV: production
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test
  artifacts:
    reports:
      junit: test-results.xml
  coverage: '/Lines.*:\s(\d+\.\d+)\%/'

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t myapp:$IMAGE_TAG .
    - docker push myapp:$IMAGE_TAG
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
  only:
    - main
  when: manual   # require manual trigger

Builds em Matrix

Builds em matrix rodam um job várias vezes com variáveis diferentes. GitHub Actions usa strategy.matrix com include/exclude. GitLab usa parallel.matrix. fail-fast: false impede que uma falha cancele os irmãos. Útil para testes multiplataforma e multiversão. A sintaxe ${{ }} precisa ser escapada em literais YAML.

yaml
# GitHub Actions matrix
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          - os: windows-latest
            node: 18
        include:
          - os: ubuntu-latest
            node: 20
            experimental: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

# GitLab CI matrix (parallel matrix):
# test:
#   image: node:${NODE_VERSION}
#   parallel:
#     matrix:
#       - NODE_VERSION: [18, 20, 22]
#         OS: [linux, macos]

Workflows Reutilizáveis e Includes

Ambos os sistemas suportam reuso. GitHub Actions usa reusable workflows (gatilho workflow_call) invocados com uses:. GitLab usa include (project, local, template, remote). O reuso reduz duplicação de lógica de CI compartilhada. Passe inputs/secrets explicitamente para manter workflows componíveis e auditáveis.

yaml
# GitHub Actions: reusable workflow
# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          TOKEN: ${{ secrets.token }}

# Caller:
# jobs:
#   build:
#     uses: ./.github/workflows/reusable.yml
#     with:
#       node-version: '20'
#     secrets:
#       token: ${{ secrets.MY_TOKEN }}

# GitLab CI: include
# include:
#   - project: 'ci/templates'
#     file: '/node.yml'
#   - local: '/.gitlab/extra.yml'
#   - template: Jobs/SAST.gitlab-ci.yml

Âncoras em Configs de CI

Âncoras YAML reduzem duplicação em configs de CI. GitLab CI as usa intensivamente: defina um job oculto (.template) com &âncora, depois <<: *âncora para mesclar. GitHub Actions suporta âncoras, mas desencoraja entre jobs (prefira reusable workflows). Âncoras deixam as configs DRY, mas mais difíceis de rastrear — use com critério.

yaml
# YAML anchors reduce duplication in CI configs
# GitLab CI commonly uses anchors

.default_template: &default_template
  image: node:20
  before_script:
    - npm ci
  cache:
    paths:
      - node_modules/

test:
  <<: *default_template
  script:
    - npm test

lint:
  <<: *default_template
  script:
    - npm run lint

build:
  <<: *default_template
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

# GitHub Actions supports anchors too (since 2022):
# jobs:
#   base: &base
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#   test:
#     uses: ./.github/workflows/reusable.yml
#   # Anchors across jobs are limited — prefer reusable workflows

Environments e Secrets

Environments do GitHub Actions gateiam implantações (exigem aprovação, restringem a branches) e guardam secrets com escopo de environment. Secrets são referenciados via ${{ secrets.NAME }}. GitLab usa variáveis protected (restritas a branch) e masked (ocultas no log), definidas na UI. Nunca registre secrets no log — podem vazar na saída de erro.

yaml
# GitHub Actions: environments & secrets
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production        # requires approval if configured
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
          ENV: production

# Secret scopes:
# - Repository secrets: available to all workflows
# - Environment secrets: only when job uses that environment
# - Organization secrets: shared across repos

# GitLab CI: protected/masked variables
# variables:
#   # defined in UI: Settings > CI/CD > Variables
#   # - Protected: only on protected branches/tags
#   # - Masked: hidden in job logs
# deploy:
#   script:
#     - ./deploy.sh
#   environment:
#     name: production
#   only:
#     - main
17

Considerações de Segurança

Riscos de Desserialização

A desserialização YAML é perigosa porque tags como !!python/object/apply podem chamar funções arbitrárias. O yaml.load() do PyYAML era inseguro por padrão antes da 5.1 (execução de código a partir de entrada não confiável). Sempre use yaml.safe_load() para entrada não confiável — ele rejeita tags de instanciação de objetos. Outras linguagens têm perigos semelhantes (SnakeYAML, Psych).

yaml
# YAML deserialization can be DANGEROUS.
# Some loaders let YAML instantiate arbitrary objects.

# DANGEROUS (PyYAML < 5.1, default was unsafe):
# data = yaml.load(untrusted_input)
# An attacker can craft YAML that runs arbitrary code:
# !!python/object/apply:os.system ["rm -rf /"]

# Other dangerous tags:
# !!python/object/apply:...     # call any Python function
# !!python/object/new:...       # instantiate any class
# !ruby/object:...               # Ruby object instantiation
# !java/object:...               # Java (SnakeYAML)

# Safe loaders reject these tags by default.
# Modern PyYAML (>= 5.1): yaml.load() requires a SafeLoader
# yaml.safe_load() is ALWAYS safe.

# Rule of thumb:
# - NEVER use yaml.load() on untrusted input
# - ALWAYS use yaml.safe_load() (or full_load on trusted files)
# - Or use a schema-validated loader

safe_load vs load

Sempre use safe_load (Python), safe_load (Psych do Ruby) ou schemas seguros por padrão (js-yaml, yaml.v3 do Go). PyYAML 5.1+ exige Loader explícito para yaml.load(). full_load permite tags padrão, mas não objetos arbitrários — use só em arquivos confiáveis. Loaders seguros rejeitam todas as tags de instanciação de objetos.

yaml
# Python (PyYAML) — the classic safe/unsafe distinction

# SAFE: safe_load rejects all custom tags
import yaml
data = yaml.safe_load(untrusted_yaml)   # ALWAYS use this

# SAFE: load with SafeLoader (explicit)
data = yaml.load(untrusted_yaml, Loader=yaml.SafeLoader)

# FULL (trusted files only): full_load allows standard tags
# but not arbitrary python objects
data = yaml.full_load(trusted_yaml)

# UNSAFE: UnsafeLoader allows !!python/object — DANGEROUS
data = yaml.load(untrusted_yaml, Loader=yaml.UnsafeLoader)  # NEVER on untrusted

# PyYAML 5.1+ requires Loader argument for yaml.load()
# (raises error without it) — safety improvement.

# Other languages:
# JS (js-yaml): yaml.load(str) uses DEFAULT_SAFE_SCHEMA
# Go (yaml.v3): no object instantiation (safe by design)
# Ruby (Psych): Psych.safe_load is the safe variant
# Java (SnakeYAML): SafeConstructor for safe loading

Exploits com Tags Locais

Tags personalizadas (!include, !env, !file, !exec, !template) podem ser exploradas mesmo sem !!python/object. Um !include que lê arquivos pode ser induzido a ler /etc/passwd ou .ssh/id_rsa via path traversal. Audite cada construtor personalizado: valide caminhos contra allowlists, recuse caminhos absolutos e ../, faça sandbox do loader.

yaml
# Even non-builtin tags can be exploited if your loader
# registers constructors that have side effects.

# Example: a "harmless" custom tag
# yaml.add_constructor('!include', include_file)
#
# If !include reads files from disk, an attacker can
# craft YAML to read sensitive files:
# config: !include /etc/passwd
# or:
# config: !include /etc/shadow
# or:
# config: !include ../../../.ssh/id_rsa

# Mitigation:
# 1. Validate the included path against an allowlist
# 2. Restrict !include to a specific directory
# 3. Refuse absolute paths and ../ traversal
# 4. Run the loader in a sandbox

# Other "innocent" tags that can be exploited:
# !env VAR_NAME        -> leaks env vars
# !exec "command"      -> arbitrary command execution
# !file /path          -> file disclosure
# !template <% ... %>  -> code injection

# Audit every custom constructor for side effects.

Billion Laughs e DoS

O ataque Billion Laughs usa aliases aninhados para expandir um documento minúsculo em gigabytes de memória (10 aliases por nível, 5 níveis = 10^9 referências). Mitigue com limites de profundidade de alias, limites de tamanho total, parsers de streaming e rejeição de aninhamento excessivo. Fique atento também a aninhamento profundo (estouro de pilha) e coleções planas enormes.

yaml
# "Billion Laughs" attack — exponential expansion via aliases
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol","lol"]
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a,*a]
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b,*b]
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c,*c]
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d,*d]

# This 5-line document expands to ~10^9 string references
# consuming gigabytes of memory on parse.

# Mitigations:
# 1. Limit alias depth (some parsers do this)
# 2. Limit total parsed size / memory
# 3. Use a streaming parser for untrusted input
# 4. PyYAML has a limit but not all parsers do
# 5. Reject documents with excessive alias nesting

# Other DoS vectors:
# - Very deep nesting (parser stack overflow)
# - Huge flat sequences/mappings (memory)
# - Pathological number formats (regex backtracking)
# - Quadratic blowup via duplicate keys

# For untrusted input: set hard size + depth limits.

Validação de Entrada

Validação em camadas: (1) limite de tamanho, (2) safe_load para rejeitar tags perigosas, (3) verificação de tipo (espere um dict, não uma lista), (4) validação de schema (JSON Schema, Pydantic, Cue), (5) validação de domínio (regras de negócio como faixa de porta). Cada camada captura ataques diferentes. Nunca confie na estrutura — sempre valide antes de usar.

yaml
# Layered defense for untrusted YAML input:

# 1. Size limit (reject oversized input)
MAX_SIZE = 1024 * 1024  # 1 MB
if len(input_text) > MAX_SIZE:
    raise ValueError("input too large")

# 2. Safe parser (rejects dangerous tags)
import yaml
try:
    data = yaml.safe_load(input_text)
except yaml.YAMLError as e:
    raise ValueError(f"invalid YAML: {e}")

# 3. Type check (expect a mapping, not a list)
if not isinstance(data, dict):
    raise ValueError("expected a mapping at top level")

# 4. Schema validation (JSON Schema, Pydantic, etc.)
from pydantic import BaseModel, ValidationError
class Config(BaseModel):
    host: str
    port: int = 8080
try:
    config = Config(**data)
except ValidationError as e:
    raise ValueError(f"schema validation failed: {e}")

# 5. Domain validation (business rules)
if config.port < 1 or config.port > 65535:
    raise ValueError("port out of range")

Recomendações de Bibliotecas

Escolha bibliotecas seguras por padrão: PyYAML (safe_load), ruamel.yaml, js-yaml (seguro por padrão), yaml.v3 do Go, Psych.safe_load, SnakeYAML com SafeConstructor, serde_yaml. Evite yaml.load sem loader seguro explícito. Fixe versões recentes para patches de segurança. Audite construtores personalizados. Leia os docs de segurança da biblioteca.

yaml
# Safe-by-default YAML libraries by language:

# Python:
#   - PyYAML >= 5.1 (yaml.safe_load)
#   - ruamel.yaml (safe by default, round-trip mode)
#   AVOID: yaml.load without explicit SafeLoader

# JavaScript/TypeScript:
#   - js-yaml (yaml.load uses DEFAULT_SAFE_SCHEMA)
#   AVOID: yaml.load with DEFAULT_FULL_SCHEMA on untrusted

# Go:
#   - gopkg.in/yaml.v3 (no object instantiation, safe)
#   AVOID: yaml.v2 has subtle differences, prefer v3

# Ruby:
#   - Psych (Psych.safe_load)
#   AVOID: YAML.load (uses unsafe loader in old Ruby)

# Java:
#   - SnakeYAML with SafeConstructor
#   AVOID: new Yaml() without SafeConstructor on untrusted
#   (SnakeYAML had CVEs from unsafe loading)

# Rust:
#   - serde_yaml (safe by design, no arbitrary types)

# General rule:
# - Read the library's security docs
# - Pin to a recent version (security patches)
# - Use safe_load / SafeConstructor / safe schema
# - Audit custom constructors for side effects
18

Boas Práticas

Indentação Consistente

Use 2 espaços consistentemente (o padrão de fato), nunca tabs. Configure seu editor para inserir espaços em YAML. Use formatadores (prettier, yamlfixer) e linters (yamllint) para impor consistência. Indentação inconsistente é o erro YAML mais comum e quebra a análise.

yaml
# Use 2 spaces for indentation (most common)
# NEVER use tabs (YAML forbids them)

# GOOD
server:
  host: localhost
  port: 8080
  routes:
    - path: /api
      handler: apiHandler
    - path: /web
      handler: webHandler

# BAD (inconsistent)
# server:
#    host: localhost
#   port: 8080      # wrong indent

# Configure your editor:
# VS Code: "[yaml]": {"editor.insertSpaces": true, "editor.tabSize": 2}
# Vim:     autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab
# Emacs:   (add-hook 'yaml-mode-hook
#           (lambda () (setq yaml-indent-offset 2)))

# Use a formatter:
# prettier (with yaml plugin) normalizes indentation
# yamllint checks it
# yamlfixer auto-fixes issues

Estratégia de Aspas

Coloque aspas em strings que pareçam números, booleanos, null ou datas; que contenham dois-pontos/vírgulas/caracteres especiais; ou que comecem com indicadores (- ? : * & ! | > ' " % @). Caso contrário, prefira simples (sem aspas), por legibilidade. Use aspas duplas para sequências de escape (\n, \t), simples para strings literais com apóstrofos.

yaml
# Quote strings when:
# 1. They look like another type (number, bool, null, date)
version: "1.0"        # string, not float
answer: "yes"         # string, not bool (1.1)
region: "no"          # string "no", not False (1.1)
date: "2024-01-01"    # string, not date
phone: "555-1234"     # string, not number

# 2. They contain special characters
url: "https://example.com:8080"   # colon
list: "a, b, c"                    # comma
expr: "value:with:colons"          # colons

# 3. They start with special indicators (-, ?, :, *, &, !, |, >, ', ", %, @, `)
flag: "-not-a-list"
key: "?not-a-complex-key"

# Don't quote otherwise — plain is more readable
name: Alice            # no quotes needed
path: /usr/local/bin   # no quotes needed

# Prefer double quotes for escapes (\n, \t)
# Prefer single quotes for literal strings with apostrophes
greeting: "Hello\nWorld"
possessive: 'Alice''s car'

Evite Tabs e Outras Armadilhas

Evite armadilhas comuns: tabs (proibidos — use espaços), yes/no/on/off sem aspas (ambiguidade 1.1 vs 1.2), strings sem aspas com dois-pontos, espaços em branco finais, finais de linha CRLF (use LF), BOM (salve como UTF-8 sem BOM) e linhas muito longas (quebre com block scalars). Um linter captura a maioria.

yaml
# Pitfall 1: tabs for indentation (FORBIDDEN)
# Configure editor to use spaces

# Pitfall 2: yes/no/on/off as strings (1.1 vs 1.2)
# Always quote: "yes", "no", "on", "off"

# Pitfall 3: unquoted strings with colons
# bad:  url: http://x:8080
# good: url: "http://x:8080"

# Pitfall 4: trailing whitespace
# Some parsers are strict; linters always flag it
key: value   # <- no trailing spaces

# Pitfall 5: Windows line endings (CRLF)
# Use LF (\n) only — CRLF can cause subtle issues
# .gitattributes: *.yaml text eol=lf

# Pitfall 6: BOM at start of file
# Save as UTF-8 without BOM

# Pitfall 7: very long lines
# Wrap with block scalars or flow style
description: >
  This is a long description that wraps
  across multiple lines for readability.

# Pitfall 8: inconsistent key ordering
# Group related keys, be consistent

Fixação de Versão e Docs de Schema

Fixe a versão YAML com %YAML 1.2 se as diferenças 1.1 vs 1.2 importarem. Documente seu schema: campos obrigatórios/opcionais, tipos, padrões, faixas — em comentários, num arquivo JSON Schema ou no README. Fixe versões de schema no código para que a validação de config seja reproduzível. Isso reduz atrito de integração e erros de config.

yaml
# Pin the YAML version if it matters
%YAML 1.2
---
key: value

# Document your schema expectations in comments:
# Required fields:
#   - host: string (hostname or IP)
#   - port: integer (1-65535)
# Optional fields:
#   - tls: boolean (default: false)
#   - cert: string (path, required if tls: true)

config:
  host: example.com
  port: 443
  tls: true
  cert: /etc/ssl/cert.pem

# Or use a JSON Schema file (config.schema.json)
# and reference it from your docs / CI:
# "Validated against schema v1.2; see config.schema.json"

# For libraries, document the schema in the README:
# ## Configuration
# The config.yaml file must contain:
# - host (str, required)
# - port (int, required, 1-65535)
# - tls (bool, optional, default: false)

# Pin schema versions in code:
# CONFIG_SCHEMA_VERSION = "1.2"
# validate(data, schema_v1_2)

Lint no CI

Integre o lint de YAML no CI (GitHub Actions, GitLab CI) e em hooks de pre-commit. Use yamllint para sintaxe/estilo e prettier para formatação. Integração com editor (extensão YAML do VS Code, yaml-language-server) fornece lint inline e validação de schema. Capturar erros de YAML no CI é muito mais barato que em produção.

yaml
# .github/workflows/lint.yml
name: Lint YAML
on: [push, pull_request]
jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint
        run: yamllint -s .

# GitLab CI:
# yamllint:
#   image: python:3.12
#   script:
#     - pip install yamllint
#     - yamllint -s .

# Pre-commit hook (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.35.1
#     hooks:
#       - id: yamllint
#         args: [-s, --config-file, .yamllint.yml]
#   - repo: https://github.com/pre-commit/mirrors-prettier
#     rev: v3.1.0
#     hooks:
#       - id: prettier
#         types: [yaml]

# Editor integration:
# VS Code: install "YAML" extension (redhat)
#   + "yamllint" for inline linting
#   + schema validation via yaml-language-server

Estrutura e Legibilidade

Agrupe chaves relacionadas com cabeçalhos de comentário. Mantenha o aninhamento raso (3-4 níveis no máximo) — YAML profundamente aninhado é difícil de ler. Use âncoras para valores genuinamente reutilizados. Use block scalars para strings multilinha. Mantenha as linhas abaixo de 120 caracteres. Legibilidade importa porque humanos editam YAML.

yaml
# Group related keys; use comments to delineate sections
server:
  # Networking
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

  # Limits
  timeout: 30
  max_connections: 100
  retries: 3

# Keep nesting shallow (3-4 levels max)
# Deeply nested YAML is hard to read and edit.

# If a value is reused, use an anchor:
defaults: &defaults
  timeout: 30
  retries: 3

prod:
  <<: *defaults
  env: production

staging:
  <<: *defaults
  env: staging

# Use block scalars for multi-line values
script: |
  #!/bin/bash
  set -e
  echo "deploying"

# Keep lines under 120 chars; wrap with block scalars or
# multi-line flow style.
19

Recursos Avançados

Chaves de Mapeamento Complexas

O indicador ? marca uma chave complexa (um mapeamento ou sequência usados como chave). Útil para tabelas de consulta (ex.: preços por região+instância). Ressalva: muitos serializadores não preservam chaves complexas e podem convertê-las em string na saída. A maioria dos arquivos de config fica com chaves de string simples, pela simplicidade e compatibilidade com ferramentas.

yaml
# Use ? to mark a complex (non-scalar) key
? apple
: red fruit

? orange
: orange fruit

# A mapping as a key
? host: localhost
  port: 8080
: connection_string

# A sequence as a key
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
? [us-west-2, t2.micro]
: 0.0125

# Useful for lookup tables
pricing:
  ? [production, large]
  : 100
  ? [production, small]
  : 50
  ? [development, large]
  : 20

# In flow style:
{[a, b]: value, {x: 1}: other}

# Caveat: many serializers don't preserve complex keys
# and may convert them to strings on output.

Sets (!!set)

Um set YAML (!!set) é um mapeamento em que as chaves são os elementos e os valores são null. Alguns parsers o mapeiam para um tipo Set nativo. Use-o para declarar coleções únicas (papéis, permissões). Ressalva: JSON não tem tipo Set, então a conversão para JSON produz um objeto com valores null. Nem cada um dos serializadores preservam a tag !!set.

yaml
# A set is a mapping with null values
# Use the !!set tag for clarity
permissions: !!set
  ? read
  ? write
  ? execute

# Equivalent to:
permissions:
  read: null
  write: null
  execute: null

# Or in flow style:
flags: !!set { red, green, blue }

# Parsers may map this to a native Set type:
# Python: set() (PyYAML with !!set constructor)
# Ruby: Set (Psych)
# JavaScript: depends on library

# Use case: declare a unique collection
roles: !!set
  ? admin
  ? editor
  ? viewer

# Caveat: JSON has no Set type, so JSON conversion
# usually produces an object with null values.

Mapeamentos Ordenados (!!omap)

!!omap (ordered mapping) é uma sequência de mapeamentos de chave única que preserva a ordem de inserção. Útil para linhas do tempo, preferências ordenadas ou onde a ordem tem significado semântico. Parsers modernos preservam a ordem de mapeamentos comuns de qualquer forma (dict do Python 3.7+, Hash do Ruby), mas maps do Go são aleatórios — !!omap torna a ordem explícita ali.

yaml
# An ordered mapping preserves key order
# Use !!omap tag
timeline: !!omap
  - 2024-01-01: event A
  - 2024-02-01: event B
  - 2024-03-01: event C

# Equivalent representation as a list of single-key mappings:
# timeline:
#   - 2024-01-01: event A
#   - 2024-02-01: event B
#   - 2024-03-01: event C

# Parsers may map this to:
# Python: list of tuples, or OrderedDict
# Ruby: Array of one-key hashes (or OrderedDict)
# Go: ordered map (with custom type)

# Use case: ordered key-value pairs where order matters
# - event timelines
# - ordered preferences
# - step-by-step configurations

# Caveat: regular YAML mappings DO preserve order in
# most modern parsers (Python dict 3.7+, Ruby Hash,
# Go map iteration is random though). !!omap makes the
# intent explicit and works even where maps are unordered.

Dados Binários (!!binary)

!!binary codifica dados binários como base64 em YAML. Parsers os decodificam para bytes nativos (bytes do Python, string ASCII-8BIT do Ruby). Útil para embutir imagens ou ícones pequenos diretamente. Para dados binários grandes, prefira referenciar por caminho ou URL. Base64 multilinha funciona com block scalars folded (>) ou literal (|).

yaml
# Encode binary data as base64 with !!binary tag
image: !!binary "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9
  awAAAABJRU5ErkJggg=="

# Multi-line base64 (folded or literal works)
data: !!binary |
  iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42m
  k+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==

# Parsers decode to bytes:
# Python: bytes object
# Ruby: ASCII-8BIT string
# JavaScript: depends on library (often base64 string)

# Use case: embed small images, icons, or other binary
# directly in YAML config

# For larger binary data, prefer:
# - Reference by path:  image: /path/to/image.png
# - Reference by URL:   image: https://example.com/img.png
# - Store separately and link

# Verify with:
# python -c 'import yaml; d=yaml.safe_load(open("f.yaml")); print(len(d["image"]))'

Construtores Personalizados

Registre construtores personalizados para mapear tags (!money) para objetos nativos. Use add_constructor com um loader com escopo SafeLoader. Construtores recebem o loader e o nó; use construct_scalar/mapping/sequence para ler o valor do nó. Sempre audite construtores quanto a efeitos colaterais (leitura de arquivos, chamadas de subprocesso) — podem ser explorados via entrada não confiável.

yaml
# PyYAML: register a constructor for a custom tag
import yaml

class Money:
    def __init__(self, currency, amount):
        self.currency = currency
        self.amount = amount
    def __repr__(self):
        return f"Money({self.currency} {self.amount})"

def money_constructor(loader, node):
    value = loader.construct_scalar(node)  # "USD 19.99"
    currency, amount = value.split()
    return Money(currency, float(amount))

# Register the constructor (use SafeLoader scope)
yaml.add_constructor('!money', money_constructor, Loader=yaml.SafeLoader)

# Now this YAML parses to a Money object:
# price: !money "USD 19.99"
config = yaml.safe_load("price: !money \"USD 19.99\"")
print(config['price'])  # Money(USD 19.99)

# Multi-argument constructors use construct_mapping or
# construct_sequence depending on the node kind.

# SECURITY: audit every constructor for side effects.
# A constructor that calls open(), os.system(), or
# subprocess can be exploited via untrusted input.

Recursos e Futuro do YAML 1.2

YAML 1.2 tornou JSON um subconjunto estrito, restringiu booleanos a true/false e adotou 0o para octal. A merge key << foi removida da especificação central, mas ainda é amplamente suportada. YAML 1.2.2 (2021) esclareceu a especificação; 1.3 está em desenvolvimento. Prepare-se para o futuro fixando a versão, colocando aspas em strings ambíguas e considerando Cue/Dhall/Jsonnet para configuração complexa.

yaml
# YAML 1.2 (2009, current spec) key changes from 1.1:
# - JSON is a strict subset
# - Booleans: only true/false (not yes/no/on/off)
# - Octal: 0o prefix (not leading 0)
# - Removed sexagesimal numbers
# - Removed merge key << from core spec (still widely supported)

# YAML 1.3 (in development) aims to:
# - Clarify ambiguous parts of 1.2
# - Standardize error reporting
# - Improve interoperability between parsers
# - Possibly restore some 1.1 features as optional

# YAML 1.2.2 (2021 update, spec revision):
# - Clarified type resolution
# - Better-defined core schema
# - Improved examples
# - No breaking changes

# Recommended practices for future-proofing:
# 1. Pin %YAML 1.2 in critical files
# 2. Quote ambiguous strings (yes/no, leading-zero numbers)
# 3. Avoid relying on << merge key for new formats
#    (or document that you depend on it)
# 4. Use JSON-compatible subset when interop matters
# 5. Watch for YAML 1.3 adoption in your parser

# Some tools (Cue, Dhall, Jsonnet) extend/replace YAML
# for complex configuration — consider them for new
# projects with advanced needs.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.