YAML es uno de esos formatos que quizás uses a diario sin haberte sentado nunca a aprenderlo en serio. Copias un workflow de GitHub Actions de una entrada de blog, ajustas un archivo de Docker Compose o editas un manifiesto de Kubernetes, y en su mayoría funciona. Hasta que no funciona, y pasas veinte minutos descubriendo que usaste una tabulación en lugar de espacios.
Esta guía explica qué es realmente YAML, cómo funciona su sintaxis y dónde es probable que te lo encuentres.
TL;DR — YAML en 30 segundos
- YAML es un formato de datos que usa indentación, no llaves, para mostrar la estructura. Maneja el mismo modelo de datos que JSON: cadenas, números, booleanos, null, listas y mapeos.
- Prescindir de las llaves y las comas hace que sea más fácil de leer y escribir para las personas, y por eso domina en los archivos de configuración.
- Kubernetes, GitHub Actions, Docker Compose y Ansible funcionan todos con YAML.
- A diferencia de JSON, YAML admite comentarios, cadenas multilínea y anclas para reutilizar valores.
- Para convertir YAML en JSON, pégalo en la herramienta YAML a JSON de FormatArc: se ejecuta por completo en tu navegador y muestra el número de la línea que falla cuando hay errores.
Qué significa YAML
YAML significaba originalmente "Yet Another Markup Language" (otro lenguaje de marcado más), pero más tarde se rebautizó con el acrónimo recursivo "YAML Ain't Markup Language" (YAML no es un lenguaje de marcado). El cambio de nombre refleja el propósito del formato: YAML está pensado para la serialización de datos, no para el marcado de documentos. No intenta hacer lo que hacen HTML o XML.
El formato fue propuesto por primera vez en 2001 por Clark Evans, y desde entonces ha pasado por varias revisiones de la especificación. La versión más utilizada en la actualidad es YAML 1.2, que se diseñó para ser un superconjunto de JSON. Eso significa que cualquier documento JSON válido es, técnicamente, también un YAML válido, aunque nadie escribe YAML de esa manera en la práctica.
Cómo se ve YAML
Aquí tienes un documento YAML sencillo:
name: Alice
age: 30
isStudent: false
Compáralo con el equivalente en JSON:
{
"name": "Alice",
"age": 30,
"isStudent": false
}
YAML prescinde de las llaves, de las comillas dobles alrededor de las claves y de las comas. En su lugar, usa la indentación para mostrar la estructura. Para mucha gente, esto hace que YAML sea más fácil de leer de un vistazo, sobre todo en los archivos de configuración que las personas editan con frecuencia.
Reglas de indentación
Aquí es donde YAML se gana su fama de quisquilloso. Las reglas son sencillas, pero las consecuencias de incumplirlas no siempre son evidentes.
Solo espacios, nada de tabulaciones
YAML requiere espacios para la indentación. Las tabulaciones no están permitidas. La mayoría de los editores se pueden configurar para insertar espacios cuando pulsas Tab, pero si tu editor no está configurado así, obtendrás errores de análisis que pueden ser difíciles de diagnosticar.
Profundidad de indentación uniforme
Tú eliges cuántos espacios usar para indentar (dos espacios es la convención más común), pero debes ser uniforme dentro de un mismo bloque. Mezclar indentación de dos espacios y de cuatro espacios en el mismo nivel de anidamiento romperá las cosas.
# This is fine
server:
host: localhost
port: 8080
# This will cause problems
server:
host: localhost
port: 8080 # wrong — different indent level than host
El anidamiento muestra la jerarquía
La indentación define las relaciones padre-hijo. Todo lo que está indentado bajo una clave pertenece a esa clave.
database:
primary:
host: db-primary.example.com
port: 5432
replica:
host: db-replica.example.com
port: 5432
Esto equivale a objetos anidados en JSON. Las claves primary y replica son hijas de database, y cada una tiene su propio host y port.
Tipos de datos
YAML infiere los tipos a partir de los valores. No necesitas declararlos, pero sí necesitas saber cómo interpretará YAML tus valores.
Cadenas
La mayoría de los valores que no son obviamente otra cosa se tratan como cadenas. Puedes ponerlos entre comillas, pero a menudo no hace falta.
city: Tokyo
greeting: "Hello, world"
path: '/usr/local/bin'
Las comillas son obligatorias cuando tu valor contiene caracteres que YAML interpretaría como sintaxis, como los dos puntos, las almohadillas o ciertos caracteres especiales al inicio.
# Without quotes, this breaks
message: "Note: this needs quotes"
selector: "#main-content"
Números
Los enteros y los decimales se reconocen automáticamente.
count: 42
ratio: 3.14
hex: 0xFF
Booleanos
Aquí tienes uno de los comportamientos más sorprendentes de YAML. Todos estos se interpretan como booleanos:
a: true
b: false
c: yes
d: no
e: on
f: off
Los alias yes/no y on/off pillan a la gente desprevenida con frecuencia. Si tienes un campo donde "yes" o "no" deberían ser una cadena (por ejemplo, un código de país como NO para Noruega), tienes que ponerlo entre comillas.
country: "NO" # string, not boolean false
YAML 1.2 endureció esto y solo reconoce true y false, pero muchos analizadores siguen admitiendo el comportamiento antiguo por compatibilidad.
Null
value: null
also_null: ~
and_this:
Los tres representan null. Un valor vacío (solo la clave sin nada después de los dos puntos) también es null.
Arrays
Los arrays usan un guion seguido de un espacio:
colors:
- red
- green
- blue
También puedes escribir arrays en línea usando corchetes, lo que se parece exactamente a JSON:
colors: [red, green, blue]
Objetos
Los objetos no son más que pares clave-valor indentados, como se muestra a lo largo de esta guía. La sintaxis en línea usa llaves:
point: {x: 10, y: 20}
Comentarios
Esta es una de las ventajas reales de YAML frente a JSON. Puedes añadir comentarios con #.
# Database configuration
database:
host: localhost # override in production
port: 5432
name: myapp
El analizador ignora los comentarios. Son muy valiosos en archivos de configuración donde necesitas explicar por qué se ha fijado un valor concreto, o dejar notas para la siguiente persona que edite el archivo.
JSON no tiene ninguna sintaxis de comentarios, y esa es una de las principales razones por las que la gente prefiere YAML para la configuración. Para una comparación completa de los dos formatos, consulta YAML frente a JSON: cómo elegir el formato adecuado.
Cadenas multilínea
YAML tiene dos indicadores especiales para las cadenas multilínea, y se comportan de forma diferente.
Bloque literal ( | )
Conserva los saltos de línea exactamente como están escritos:
description: |
This is line one.
This is line two.
This is line three.
La cadena resultante contiene los saltos de línea entre cada renglón.
Bloque plegado ( > )
Pliega los saltos de línea en espacios, creando una sola línea larga:
description: >
This is a long paragraph
that will be joined into
a single line.
El resultado es "This is a long paragraph that will be joined into a single line.", útil para descripciones largas que quieres dividir en varias líneas dentro de tu archivo YAML para que sea más legible.
Anclas y alias
YAML tiene una función para reutilizar valores. Defines un ancla con & y la referencias con *.
defaults: &default_settings
timeout: 30
retries: 3
production:
<<: *default_settings
timeout: 60
staging:
<<: *default_settings
La clave de fusión << copia todos los valores del ancla, y puedes sobrescribir claves individuales. Esto reduce la duplicación en archivos de configuración grandes, aunque puede hacer que el archivo sea más difícil de seguir si se abusa de ello.
Dónde se usa YAML
Kubernetes
Kubernetes es probablemente el mayor impulsor del uso de YAML hoy en día. Todos los recursos de Kubernetes (pods, deployments, services, configmaps) se definen en YAML.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
Estos manifiestos pueden volverse largos, y pequeños errores de indentación pueden provocar fallos de despliegue confusos. Muchos equipos validan su YAML antes de aplicarlo.
GitHub Actions
Los workflows de GitHub Actions viven en .github/workflows/ y se escriben en YAML.
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install
- run: npm test
Docker Compose
Docker Compose usa YAML para definir aplicaciones de múltiples contenedores.
services:
web:
image: nginx
ports:
- "80:80"
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
Otras herramientas
Playbooks de Ansible, charts de Helm, plantillas de CloudFormation, especificaciones de Swagger/OpenAPI, configuraciones de sitios de Jekyll y Hugo: YAML es el formato de referencia para las herramientas que necesitan una configuración editable por personas.
Errores comunes
Usar tabulaciones
El error de YAML más común. Tu archivo parece perfectamente indentado en tu editor, pero el analizador lo rechaza porque hay caracteres de tabulación ocultos en los espacios en blanco. Configura tu editor para que muestre los caracteres invisibles si estás depurando un error de YAML misterioso.
Cadenas especiales sin comillas
Valores como yes, no, on, off, null y ~ se interpretan como booleanos o como null. Marcas de tiempo como 2026-03-20 se analizan como objetos de fecha en algunos analizadores. Ante la duda, pon tus cadenas entre comillas.
Indentación no uniforme
Mezclar indentación de dos y de cuatro espacios, o indentar accidentalmente una clave con un espacio de más, produce errores que pueden ser difíciles de localizar en un archivo grande.
Olvidar el espacio después de los dos puntos
key:value no es lo mismo que key: value. El espacio después de los dos puntos es obligatorio.
Conversión entre YAML y JSON
Como YAML 1.2 es un superconjunto de JSON, la conversión entre ambos es sencilla. Todo documento YAML se puede representar como JSON, aunque en el proceso pierdes los comentarios y el formato de las cadenas multilínea.
Convertir resulta útil cuando necesitas pasar una configuración en YAML a una herramienta que espera JSON, o cuando quieres validar la estructura de tu YAML viéndola en un formato más explícito.
Puedes convertir YAML a JSON al instante usando la herramienta YAML a JSON. Pega tu YAML y obtendrás una salida JSON limpia. Para un recorrido paso a paso, consulta Cómo convertir YAML a JSON.
En el sentido contrario, el conversor de JSON a YAML convierte respuestas de API en JSON o configuraciones en YAML limpio dentro del navegador, práctico para construir manifiestos de Kubernetes o archivos de Docker Compose a partir de JSON. La guía de JSON a YAML repasa en detalle las reglas de conversión.
Preguntas frecuentes
¿Qué significa YAML?
"YAML Ain't Markup Language" (YAML no es un lenguaje de marcado). Originalmente significaba "Yet Another Markup Language" (otro lenguaje de marcado más), pero se renombró con este acrónimo recursivo para dejar claro que YAML está pensado para la serialización de datos, no para el marcado de documentos.
¿Es YAML un lenguaje de programación?
No. YAML es un formato de serialización de datos que se usa para archivos de configuración e intercambio de datos. No tiene flujo de control: ni condicionales ni bucles.
¿Hay diferencia entre .yml y .yaml?
No. Ambas extensiones se analizan de forma idéntica. La especificación recomienda .yaml, pero .yml también se usa mucho, a menudo solo para ahorrar un carácter.
¿Por qué Kubernetes y GitHub Actions usan YAML?
Porque es legible para las personas y admite comentarios, de modo que puedes documentar por qué un ajuste tiene el valor que tiene. La ausencia de llaves y comas le sienta bien a los archivos de configuración que la gente edita a mano.
¿En qué se diferencia YAML de JSON?
YAML y JSON comparten el mismo modelo de datos, pero YAML añade comentarios, cadenas multilínea y anclas, y usa indentación en lugar de llaves. JSON es más estricto y más rápido de analizar, lo que le va bien a las APIs. Para una comparación lado a lado completa, consulta YAML frente a JSON.
¿Por qué country: NO se convirtió en false?
Los analizadores de YAML 1.1 (como PyYAML, que todavía se usa mucho) leen el NO sin comillas como el booleano false. Este es el famoso "problema de Noruega". Ponlo entre comillas (country: "NO") para que siga siendo una cadena. Consulta la guía de sintaxis de YAML para más detalles.
Para terminar
El atractivo de YAML viene de su legibilidad. Para los archivos de configuración que las personas editan con regularidad, la ausencia de llaves y comillas marca una diferencia real. La contrapartida es que los errores de indentación pueden ser sutiles y que algunas de las reglas de inferencia de tipos de YAML resultan sorprendentes.
Si trabajas con YAML con regularidad, vale la pena dedicar una hora a aprender bien las reglas en lugar de copiar y pegar esperando que todo salga bien. Entender la indentación, las reglas de las comillas y la coerción de tipos te ahorrará la mayoría de los dolores de cabeza relacionados con YAML. Para una referencia paso a paso de cada construcción de YAML (anclas, archivos multidocumento, indicadores de recorte), consulta la guía de sintaxis de YAML.
Para una comparación cara a cara de YAML y JSON, incluido cuándo usar cada uno, lee YAML frente a JSON: cómo elegir el formato adecuado.
Lecturas relacionadas
- Guía de sintaxis de YAML: cada construcción, desde la indentación hasta las anclas, con ejemplos
- YAML frente a JSON: cuándo elegir cada formato
- Cómo convertir YAML a JSON: recorrido de conversión paso a paso
- Guía de sintaxis de JSON: el formato con el que más se compara YAML
- Comentarios en JSON y JSONC: lo que ofrece YAML y JSON no
- Cómo convertir JSON a YAML: el sentido inverso, para configuraciones de Kubernetes y Docker