YAML es el formato de configuración preferido para Docker, Kubernetes y pipelines CI/CD. A pesar de su sintaxis amigable, es sorprendentemente fácil cometer errores.
Dónde se usa YAML
- Docker Compose
- Manifiestos Kubernetes
- GitHub Actions / GitLab CI
- Playbooks Ansible
- Archivos de configuración
Reglas de sintaxis básicas
Indentación
YAML usa espacios (nunca tabulaciones):
# ✅ Correct (2-space indentation)
server:
host: localhost
port: 8080
database:
name: myapp
pool: 10
# ❌ Wrong (tab characters or inconsistent spaces)
server:
host: localhost # Tab character - INVALID!
port: 8080 # 3 spaces - inconsistent!Pares clave-valor
Separados por dos puntos y espacio:
# ✅ Correct
name: John Doe
port: 8080
# ❌ Wrong - missing space after colon
name:John DoeStrings multilínea
YAML ofrece dos estilos para strings multilínea:
# | (literal block) - preserves newlines
description: |
This is line one.
This is line two.
Each newline is preserved.
# > (folded block) - folds newlines to spaces
description: >
This is a long paragraph
that will be joined into
a single line.Tipos de datos
| Tipo | Sintaxis | Ejemplo |
|---|---|---|
| String | plain, "quoted", 'quoted' | name: John |
| Integer | 42, 0xFF, 0o77 | port: 8080 |
| Float | 3.14, .inf, .nan | pi: 3.14159 |
| Boolean | true/false | debug: true |
| Null | null, ~, (empty) | value: null |
| Date | YYYY-MM-DD | date: 2026-02-10 |
El "problema Noruega"
En YAML 1.1, `NO` se interpreta como `false`. Use comillas:
# ❌ YAML 1.1 interprets these as booleans!
country: NO # → false
answer: yes # → true
switch: on # → true
# ✅ Fix: quote the values
country: "NO" # → string "NO"
answer: "yes" # → string "yes"
switch: "on" # → string "on"Colecciones
# List (sequence)
fruits:
- apple
- banana
- cherry
# Nested map
database:
host: localhost
port: 5432
credentials:
user: admin
password: secret
# Inline / Flow style
fruits: [apple, banana, cherry]
point: {x: 10, y: 20}Top 10 errores YAML
| # | Error | Causa | Solución |
|---|---|---|---|
| 1 | Error de tabulación | Tabs para indentar | Reemplazar con espacios |
| 2 | Indentación inconsistente | Mezcla de 2 y 4 espacios | Usar indentación consistente |
| 3 | Espacio faltante | `key:value` | Agregar espacio después de `:` |
| 4 | Caracteres especiales sin comillas | Valores con : o # sin comillas | Poner entre comillas |
| 5 | Coerción booleana | yes/no como booleanos | Usar comillas |
| 6 | Strings con dos puntos | URLs rotas | Citar el valor completo |
| 7 | Claves duplicadas | Misma clave dos veces | Eliminar duplicados |
| 8 | Espacios al final | Espacios invisibles | Configurar editor |
| 9 | Error de indentación de lista | Items no alineados | Alinear `-` |
| 10 | Separador de documento faltante | Múltiples documentos sin `---` | Agregar `---` |
YAML vs JSON vs TOML
| Característica | YAML | JSON | TOML |
|---|---|---|---|
| Comments | # support | None | # support |
| Multi-line strings | | and > | \\n only | """ triple quotes |
| Data types | Rich (dates, etc.) | Basic (6 types) | Rich (dates, etc.) |
| Readability | High | Medium | High |
| Machine parsing | Complex | Simple | Medium |
| Best for | Config files | APIs, data exchange | App config |
Mejores prácticas
- Usar linter YAML en CI/CD
- Mostrar espacios en el editor
- Usar 2 espacios
- Citar strings ambiguos
- Usar validación de esquema
- Mantener archivos pequeños y modulares
FAQ
¿Se pueden usar tabulaciones en YAML?
No. YAML prohíbe estrictamente las tabulaciones para la indentación.
¿Diferencia entre comillas simples y dobles?
Simples: string literal. Dobles: permiten secuencias de escape.
¿Cómo representar null?
`null`, `~`, o valor vacío.
¿Por qué YAML trata "NO" como false?
YAML 1.1 trata yes/no como booleanos. YAML 1.2 solo reconoce true/false.