Tutorial de Sintaxis YAML: Una Introducción Práctica

YAML (YAML Ain't Markup Language) es un formato de serialización de datos legible por humanos utilizado ampliamente en archivos de configuración, pipelines de CI/CD e infraestructura como código. Si trabajas con Docker Compose, Kubernetes, GitHub Actions o Ansible, ya estás usando YAML a diario. Este tutorial cubre todo lo que necesitas para escribir YAML con confianza.

¿Por Qué YAML?

La principal ventaja de YAML es la legibilidad. Compara los mismos datos en JSON y YAML:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML logra la misma estructura con menos puntuación. Sin llaves, sin corchetes para casos simples, sin entrecomillado obligatorio. Esto hace que los archivos de configuración sean más fáciles de leer y editar a mano.

Tipos de Datos Básicos

Escalares

YAML infiere automáticamente los tipos a partir de los valores:

string: hello world          # Cadena (sin comillas necesarias)
quoted: "hello world"        # Cadena explícita
integer: 42                  # Entero
float: 3.14                  # Decimal
boolean: true                # Booleano (true/false, yes/no, on/off)
null_value: null             # Nulo (también ~ o vacío)
date: 2025-01-15             # Fecha (ISO 8601)

Error común: Valores como yes, no, on, off se interpretan como booleanos. Si te refieres a la cadena "yes", entrecomíllala: "yes".

Cadenas y Entrecomillado

Las cadenas rara vez necesitan comillas, pero algunos casos lo requieren:

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

Cadenas Multilínea

YAML tiene dos estilos multilínea:

Bloque literal (|) — preserva saltos de línea:

description: |
  Esta es la línea uno.
  Esta es la línea dos.
  
  Esta es la línea cuatro (después de línea en blanco).

Bloque plegado (>) — une líneas con espacios:

description: >
  Este es un párrafo largo
  que se plegará en
  una sola línea.

Añade - para eliminar saltos de línea finales (|-, >-) o + para conservarlos (|+, >+).

Colecciones

Listas (Secuencias)

# Estilo bloque
fruits:
  - apple
  - banana
  - cherry

# Estilo fluido (en línea)
fruits: [apple, banana, cherry]

Mapas (Mapeos)

# Estilo bloque
person:
  name: Alice
  age: 30
  city: London

# Estilo fluido
person: {name: Alice, age: 30, city: London}

Estructuras Anidadas

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

Anclas y Alias

Las anclas (&) y alias (*) te permiten reutilizar valores:

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

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Sobrescribe el valor por defecto

La clave de fusión << incorpora todas las propiedades del ancla. Las propiedades definidas después de la fusión sobrescriben los valores anclados. Lee más sobre patrones avanzados de anclas en nuestra guía de anclas y alias YAML.

Múltiples Documentos

Un solo archivo YAML puede contener múltiples documentos separados por ---:

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

Esto se usa comúnmente en manifiestos de Kubernetes.

Errores Comunes

1. Errores de Indentación

YAML usa espacios, nunca tabulaciones. La indentación inconsistente es el error más común:

# INCORRECTO - indentación mixta
server:
  host: localhost
    port: 8080  # Error: indentación inesperada

# CORRECTO
server:
  host: localhost
  port: 8080

Usa nuestro Formateador de YAML para corregir automáticamente problemas de indentación.

2. El Problema de Noruega

Los códigos de país como NO (Noruega) se interpretan como booleano false:

# INCORRECTO
countries:
  - NO  # ¡Se interpreta como false!
  - SE
  - DK

# CORRECTO
countries:
  - "NO"
  - SE
  - DK

3. Caracteres Especiales Sin Entrecomillar

Los dos puntos, almohadillas y corchetes en los valores necesitan entrecomillado:

# INCORRECTO
message: Error: file not found
url: http://example.com  # Podría fallar

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

4. Trampa de Números de Versión

Los números de versión como 1.0 se analizan como decimales:

# INCORRECTO
version: 1.0  # Se convierte en 1 (decimal)

# CORRECTO
version: "1.0"  # Cadena

Validación de YAML

Siempre valida tu YAML antes de desplegar. Los errores de sintaxis en YAML pueden causar fallos crípticos en las aplicaciones. Nuestro Validador de YAML verifica la sintaxis al instante, resaltando la línea y columna exacta de cualquier error.

Para una exploración más profunda de las diferencias entre YAML y JSON, consulta nuestra comparación YAML vs JSON.

FAQ

¿Cuántos espacios debería usar para la indentación YAML?

Dos espacios es la convención más común, utilizada por Kubernetes, Docker Compose, GitHub Actions y la mayoría de las herramientas DevOps. Algunos proyectos usan cuatro espacios. La regla clave es la consistencia dentro de un archivo — nunca mezcles niveles de indentación.

¿YAML permite comentarios?

Sí, YAML soporta comentarios de una línea con #. No existe sintaxis para comentarios multilínea. Los comentarios se eliminan durante el análisis y no están disponibles en la estructura de datos cargada.

Recursos Relacionados

• Formateador de YAML — Formatea y embellece archivos YAML
• YAML vs JSON — Cuándo usar cada formato
• YAML para Docker Compose — Patrones YAML específicos de Docker