YAML para principiantes: Dominar archivos de configuración

Si trabajas con Docker, Kubernetes, GitHub Actions o prácticamente cualquier herramienta moderna de DevOps, ya estás usando YAML, te des cuenta o no. YAML (que significa "YAML Ain't Markup Language" — sí, es un acrónimo recursivo) fue diseñado para ser el formato de datos más legible posible para humanos.

Aprendámoslo juntos, un concepto a la vez.

Por qué existe YAML

JSON es genial para las máquinas, pero ¿alguna vez has intentado escribir un archivo de configuración de 200 líneas en JSON? Sin comentarios, comillas dobles obligatorias en todas partes, llaves anidadas cinco niveles de profundidad... se vuelve doloroso rápido. YAML fue creado para resolver esto. Usa indentación en lugar de llaves, lo que hace que las configuraciones se vean limpias y fáciles de leer.

Aquí están los mismos datos en JSON y YAML. ¿Ves la diferencia?

JSON:

YAML:

Los fundamentos que necesitas saber

Los pares clave-valor son el pan de cada día de YAML. Solo usa dos puntos y un espacio: name: John Doe. Eso es todo — no se necesitan comillas para la mayoría de los strings.

La indentación lo es todo. YAML usa espacios (¡nunca tabs!) para mostrar la estructura. El estándar es 2 espacios por nivel. Si te equivocas, tu archivo se rompe. En serio — la especificación YAML es estricta con esto.

Aquí hay un ejemplo de datos anidados:

Las listas usan un guión y un espacio. Aquí hay una lista de compras en YAML:

Strings: Más complicados de lo que piensas

La mayoría de los strings no necesitan comillas en YAML. Pero deberías usarlas cuando contienen dos puntos, almohadillas o podrían ser malinterpretados. Por ejemplo, country: NO se interpreta como country: false en YAML 1.1 porque NO se trata como booleano. Este es el infame "problema de Noruega" y ha causado bugs reales en producción.

En caso de duda, ponlo entre comillas: country: "NO"

Los strings multilínea son increíbles

Aquí es donde YAML realmente brilla. El pipe | preserva los saltos de línea (genial para scripts), mientras que > los convierte en espacios (genial para descripciones largas):

Anclas y alias: archivos de configuración DRY

Una de las características más geniales de YAML. Define algo una vez con &, referéncialo después con *:

El bloque production hereda retries: 3 de defaults pero sobrescribe timeout. Esto es increíblemente útil en flujos de trabajo de GitHub Actions y archivos Docker Compose donde de otro modo repetirías los mismos bloques de configuración una y otra vez.

Los 4 errores más comunes en YAML

• Tabs en lugar de espacios — Tu editor podría insertar tabs por defecto. Configúralo para usar espacios en archivos YAML. En serio, hazlo ahora.
• Trampas de booleanos — yes, no, on, off, true, false son TODOS booleanos en YAML 1.1. Usa comillas si quieres el string.
• Dos puntos en valores — message: Error: file not found se romperá porque YAML ve un segundo separador clave-valor. Usa comillas: message: "Error: file not found"
• Espacios al final — Espacios invisibles al final de las líneas pueden causar comportamiento de parsing extraño. Usa un editor que resalte los espacios al final.

Dónde usarás YAML todos los días

YAML es el lenguaje de configuración para Docker Compose, manifiestos de Kubernetes, GitHub Actions, GitLab CI, playbooks de Ansible y docenas más. Si estás haciendo algo en DevOps o la nube, la fluidez en YAML es innegociable.

¿Tienes un archivo YAML que se comporta de forma extraña? Pégalo en nuestro YAML Validator para detectar el problema al instante.

YAML en el mundo real: Ejemplo de Docker Compose

Veamos un archivo Docker Compose realista — del tipo que realmente escribirías para una aplicación web:

Observa algunas cosas: las variables de entorno pueden escribirse como lista (- KEY=value) o como mapeo (KEY: value). Ambas funcionan en Docker Compose — pero elige un estilo y mantenlo por consistencia.

YAML en el mundo real: Pipeline CI de GitHub Actions

Aquí hay un flujo de trabajo de GitHub Actions que ejecuta tests en cada push:

Esto es limpio, legible y autoexplicativo. Imagina escribir este mismo flujo de trabajo en JSON — sería el doble de largo y mucho más difícil de leer visualmente.

YAML vs JSON vs TOML: Comparación rápida

YAML no es la única alternativa a JSON para archivos de configuración. TOML es otra opción popular (usada por Cargo.toml de Rust y pyproject.toml de Python). Así se comparan:

YAML avanzado: Múltiples documentos en un archivo

YAML soporta múltiples documentos en un solo archivo, separados por ---. Esto se usa comúnmente en Kubernetes para desplegar múltiples recursos a la vez:

El separador --- le dice al parser YAML "este es un nuevo documento." Puedes hacer kubectl apply -f en un archivo así y Kubernetes creará ambos recursos.

Seguridad YAML: El ataque Billion Laughs

Aquí hay algo que la mayoría de los principiantes no saben: YAML puede ser un riesgo de seguridad si no tienes cuidado. El ataque "Billion Laughs" usa anclas y alias para crear expansión exponencial de datos:

Este archivo diminuto puede expandirse a gigabytes en memoria y hacer que tu aplicación se cuelgue. ¿La lección? Nunca parsees entrada YAML no confiable. Usa funciones de carga segura como yaml.safe_load() en Python en lugar de yaml.load(), y establece límites de memoria en tu parser YAML.

Convertir entre YAML y JSON

Como YAML es un superconjunto de JSON (¡sí, JSON válido también es YAML válido!), convertir entre los dos es sencillo. Esto es útil cuando quieres usar la legibilidad de YAML para escribir configuraciones pero necesitas JSON para una API o herramienta que lo requiera.

Nuestro Conversor de YAML a JSON lo maneja al instante — solo pega tu YAML y obtén una salida JSON limpia. ¿En la dirección opuesta? Cualquier JSON que tengas ya es YAML válido.

Pruébalo tú mismo

Ya sea que estés depurando un manifiesto de Kubernetes roto o configurando un nuevo pipeline CI, estas herramientas te ahorrarán tiempo:

• YAML Formatter — Corrige la indentación y haz que tus archivos YAML estén limpios y consistentes.
• YAML Validator — Detecta errores de sintaxis antes de que rompan tu despliegue.
• Conversor de YAML a JSON — Convierte entre formatos cuando necesites interoperar con herramientas que solo aceptan JSON.

YAML tiene sus peculiaridades, pero una vez que te sientas cómodo con la sintaxis basada en indentación, apreciarás lo mucho más limpios que se ven tus archivos de configuración comparados con la alternativa JSON.