Plain unquoted string — most common
name: John Doe
Single-quoted: no variable or escape processing
path: '/usr/bin/node'
Double-quoted: supports escape sequences (\n, \t, etc.)
message: "Hello\nWorld"
Whole number (base 10)
port: 8080
Floating point number
threshold: 0.95
Boolean value — use only true/false (YAML 1.2)
debug: false
Null / absence of value
response: null
ISO 8601 date format
created: 2024-01-15T10:30:00Z
Single-line comment. No multi-line comment syntax.
# This is a comment key: value # inline comment
Force value to be treated as a specific type
port: !!str 8080 # string '8080' not int
Key-value pairs — indented block style
app: name: myapp port: 3000
Inline map — equivalent to block style
env: {NODE_ENV: prod, PORT: 8080}List of items — block style with dash+space
fruits: - apple - banana - cherry
Inline list — equivalent to block style
ports: [80, 443, 8080]
List where each item is a map
users:
- name: Alice
role: admin
- name: Bob
role: userArbitrarily deep nesting
database:
primary:
host: db1.example.com
port: 5432Merge the keys of a referenced mapping into current map
defaults: &defaults color: blue button: <<: *defaults text: Submit
Preserves newlines exactly as written
script: | #!/bin/bash echo "hello" exit 0
Newlines folded into spaces (great for long descriptions)
description: > This is a very long description that will be joined into one line.
Literal block, strip all trailing newlines
prompt: |- Enter value:
Literal block, keep all trailing newlines
template: |+ line1
Folded block, strip trailing newlines
message: >- This folds into one line no trailing newline
Assigns an anchor (label) to the current node
base: &base image: node:18 restart: always
References (copies) an anchored node
service1: <<: *base name: api service2: <<: *base name: worker
Anchor a scalar value to reuse it
read_timeout: &rto 30 write_timeout: *rto connect_timeout: *rto
Anchor a list
primary_colors: &colors - red - blue text_colors: *colors
Explicitly declare YAML version (optional, rarely needed)
%YAML 1.2 --- name: myapp
Marks the start of a YAML document. Required if using directives.
--- kind: Deployment --- kind: Service
Marks the end of a YAML document. Optional but useful.
--- debug: true ...
Multiple YAML docs in one file (stream)
Used in Kubernetes multi-resource files
Base64-encoded binary data
icon: !!binary | iVBORw0KGgo=
Indentation MUST use spaces only — never tabs
# WRONG: parent: \tchild: value # RIGHT: parent: child: value
Values containing ': ' (colon+space) must be quoted
# WRONG: url: http://example.com # RIGHT: url: "http://example.com"
1.0 parses as float! Quote or tag it to keep as string
version: '1.0' # string version: 1.0 # float
YAML 1.1 parses yes/no/on/off as booleans — quote to use strings
# YAML 1.1 (PyYAML): on: true # 'on' is boolean true! # Safe: always quote on: 'on'
Trailing spaces in keys are included in the key string
"key " (with space) != "key" — trim carefully
Duplicate keys — behavior is parser-specific (usually last wins). Treat as error.
Use a YAML linter to detect duplicate keys
| Funcionalidade | YAML | JSON |
|---|---|---|
| Comentários | Yes: # comment | Não suportado |
| Aspas necessárias | Opcional para strings | Obrigatório para strings |
| Anchors/aliases | Yes: &anchor / *alias | Não suportado |
| Strings multilinha | Yes: | and > blocks | Escaped \n only |
| Tabs para indentação | Somente espaços | Qualquer um |
| É um superconjunto de JSON | Todo JSON é YAML válido | - |
| Legibilidade humana | Muito alta | Médio |
| Disponibilidade de parsers | Alta | Muito alta |
Importante: Muitos parsers YAML ainda usam YAML 1.1 por defeito (PyYAML do Python, Psych do Ruby em algumas versões).
O YAML tem dois estilos multilinha:
Bloco literal (|) — preserva quebras de linha:
description: |
Esta é a linha um.
Esta é a linha dois.
Esta é a linha quatro (após linha em branco).
Bloco dobrado (>) — junta linhas com espaços:
description: >
Este é um parágrafo longo
que será dobrado numa
única linha.
Adicione - para remover novas linhas finais (|-, >-) ou + para as manter (|+, >+).
Um único ficheiro YAML pode conter múltiplos documentos separados por ---:
---
# Documento 1: Config
apiVersion: v1
kind: ConfigMap
---
# Documento 2: Service
apiVersion: v1
kind: Service
Isto é comummente utilizado em manifestos do Kubernetes.
Dois espaços é a convenção mais comum, utilizada pelo Kubernetes, Docker Compose, GitHub Actions e a maioria das ferramentas DevOps. Alguns projetos utilizam quatro espaços. A regra fundamental é a consistência dentro de um ficheiro — nunca misture níveis de indentação.
Sim, o YAML suporta comentários de linha única com #. Não existe sintaxe para comentários multilinha. Os comentários são removidos durante a análise e não ficam disponíveis na estrutura de dados carregada.
YAML é um superconjunto de JSON — qualquer JSON válido é YAML válido. YAML é concebido para ser mais legível por humanos, com suporte a comentários, strings multilinha e âncoras/aliases. JSON é mais estrito, mais rápido de analisar e universalmente suportado. Use YAML para ficheiros de configuração e JSON para APIs e troca de dados.
No YAML 1.1 (usado por muitos parsers incluindo PyYAML), 'on', 'off', 'yes', 'no' são valores booleanos válidos. Isso pode causar erros quando usados como strings simples (por ex., no Ansible). O YAML 1.2 corrigiu isso — apenas 'true' e 'false' são booleanos. Solução: coloque sempre esses valores entre aspas ('yes', 'no') se quiser usá-los como strings.
Use o literal block scalar (|) para preservar quebras de linha: cada linha no bloco torna-se uma quebra de linha literal na string. Use o folded block scalar (>) para converter quebras de linha em espaços: ótimo para parágrafos longos. Ambos suportam indicadores de chomping opcionais (- para remover quebras de linha finais, + para manter todas).
YAML usa espaços para indentação — nunca tabulações. Todas as chaves irmãs devem estar no mesmo nível de indentação. Misturar tabulações e espaços causará sempre erros. Correções comuns: ative a definição 'substituir tabulações por espaços' no seu editor, use um linter (yamllint), garanta uma largura de indentação consistente (2 ou 4 espaços) em todo o ficheiro.