Guía definitiva para validar archivos YAML

Los archivos YAML se han convertido en una pieza clave en el desarrollo moderno de soluciones. Si alguna vez has trabajado con Docker, Kubernetes, GitHub Actions, Ansible o incluso con la documentación de APIs en OpenAPI/Swagger, entonces ya has usado YAML, aunque quizá no lo hayas notado.

Es probable que en algún momento te hayas encontrado con un error extraño, de esos que parecen imposibles de entender: “unexpected indentation”, “mapping values are not allowed here” o simplemente que tu aplicación no arranca. Y todo porque… había un espacio de más.

En este artículo vamos a recorrer, paso a paso, todo lo que necesitas saber sobre cómo validar un archivo YAML. Desde lo más básico —qué es y cómo se estructura— hasta métodos avanzados para asegurarte de que no solo es correcto en su sintaxis, sino también válido en el contexto en el que se usa.

Prepárate para un recorrido práctico: al final tendrás una caja de herramientas para enfrentarte a cualquier archivo YAML sin miedo.

Qué es YAML y por qué es tan popular

Antes de hablar de validación, tenemos que entender qué es YAML y por qué se usa tanto.

YAML significa “YAML Ain’t Markup Language”, una especie de chiste autorreferencial (algo muy para dar nombre a soluciones de software). Originalmente se diseñó como un lenguaje de serialización de datos muy legible para humanos. Es una alternativa más clara y menos ruidosa que JSON o XML.

Ejemplo en JSON:

{
  "nombre": "Ana",
  "edad": 28,
  "habilidades": ["Python", "Docker", "Kubernetes"]
}

El mismo ejemplo en YAML:

nombre: Ana
edad: 28
habilidades:
  - Python
  - Docker
  - Kubernetes

Notarás que en YAML no hacen falta llaves {}, ni corchetes [], ni comillas obligatorias. Al igual que Python, todo depende de la indentación, lo que lo hace más fácil de leer… pero también más propenso a errores.

Por eso validar un YAML es tan importante. Un espacio mal puesto puede ser la diferencia entre un despliegue exitoso y una noche en vela.

El talón de Aquiles de YAML: la indentación

La belleza de YAML radica en su simplicidad, pero esa misma simplicidad puede ser peligrosa. Como todo depende de la indentación (espacios, no tabuladores), un error mínimo puede romper el archivo.

Por ejemplo, este YAML es válido:

usuario:
  nombre: Ana
  edad: 28

Pero si alguien mezcla tabuladores y espacios:

usuario:
     nombre: Ana
     edad: 28

El resultado es un error al cargarlo.

Por eso, la primera forma de validar un YAML es asegurarte de que no hay tabuladores y de que la indentación es consistente. Normalmente se usan 2 espacios o 4 espacios, pero nunca mezclar.

Tres niveles de validación en YAML

Cuando hablamos de “validar un YAML”, no siempre hablamos de lo mismo. Existen tres niveles:

1. Validación sintáctica: el archivo está bien formado (sin errores de indentación, comillas, etc.).
2. Validación estructural: el archivo tiene sentido dentro del contexto en el que se usa (ej. Docker, Kubernetes, GitHub Actions).
3. Validación contra esquemas: el archivo cumple con una definición formal (ej. OpenAPI 3.0, JSON Schema, etc.).

Ejemplo:

• Un docker-compose.yaml puede ser sintácticamente correcto, pero si olvidaste la sección services, Docker lo rechazará.
• Un openapi.yaml puede ser legible, pero si el campo servers está mal definido, la especificación será inválida.

En esta guía veremos cómo cubrir los tres niveles.

Validar YAML online: lo más rápido

La forma más sencilla (y muchas veces la primera que usamos) es copiar y pegar el archivo en un validador online. Algunos populares son:

• YAML Lint
• Code Beautify YAML Validator

Ventajas:

• Rápido, sin instalación.
• Perfecto para archivos pequeños.

Desventajas:

• Poco práctico para proyectos grandes.
• No valida contexto (solo sintaxis).

Ejemplo de uso en YAML Lint:

• Pega este YAML válido:

app:
  name: blog
  version: 1.0

• Ahora prueba con este YAML roto:

app
  name: blog
  version: 1.0

Verás un error indicando que falta el :.

Validar YAML en local con yamllint

Cuando los proyectos crecen, usar validadores online deja de ser práctico. Aquí entra yamllint, una herramienta de línea de comandos.

Para instalar esta herramienta se puede reucurrir a pip, ya que esta basada en Python.

pip install yamllint

Una vez instalada, se puede validar simplemente ejecutando un comando como el que se muestra a continuación:

yamllint archivo.yaml

Si el archivo es válido, no verás errores. Si hay problemas, mostrará la línea exacta:

archivo.yaml
  3:1       error    too many spaces inside braces  (braces)

Integración con VS Code

Si usas VS Code, puedes instalar la extensión YAML (Red Hat). Esta extensión usa internamente validadores como yamllint y muestra errores en tiempo real.

Validar YAML con Python

Otra forma práctica es usar la librería pyyaml para cargar el archivo y ver si hay errores.

import yaml

with open("archivo.yaml", "r") as f:
    try:
        data = yaml.safe_load(f)
        print("YAML válido")
    except yaml.YAMLError as e:
        print("Error:", e)

Esto es útil si quieres integrar validación dentro de un script o pipeline.

Validar en el contexto: Docker, Kubernetes, OpenAPI

Validar la sintaxis es necesario, pero no suficiente. Necesitamos comprobar que el YAML funciona en su contexto.

Docker Compose

docker compose config

Esto combina y valida todos los docker-compose.yaml antes de levantar los servicios.

Kubernetes

kubectl apply --dry-run=client -f deployment.yaml

Permite probar un manifiesto sin aplicarlo realmente.

OpenAPI

Si tu YAML define una API:

npm install -g swagger-cli
swagger-cli validate openapi.yaml

Esto valida la especificación contra el estándar OpenAPI 3.x.

Validar contra esquemas

En algunos casos, no basta con saber que el archivo “funciona”. Queremos asegurarnos de que cumple con un esquema formal.

Ejemplo en VS Code: podemos asociar un esquema a un archivo YAML desde settings.json:

"yaml.schemas": {
  "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.0/schema.yaml": "openapi.yaml"
}

Así, cada vez que edites openapi.yaml, VS Code validará automáticamente según la especificación oficial.

También puedes usar herramientas como pykwalify (Python) para validar contra un esquema definido en YAML.

Validación en CI/CD

Lo ideal es no esperar a que un error aparezca en producción. Podemos automatizar la validación en pipelines de CI/CD.

Ejemplo en GitHub Actions (.github/workflows/lint.yml):

name: YAML Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install yamllint
        run: sudo apt-get install yamllint -y
      - name: Run yamllint
        run: yamllint .

Cada vez que subas un cambio, el pipeline validará todos los YAML del repositorio.

Buenas prácticas para evitar errores en YAML

A la hora de vaciar archivos YAML es bueno seguir las siguientes buenas prácticas:

• Usa siempre espacios, nunca tabuladores.
• Mantén la indentación consistente (2 o 4 espacios).
• Comillas: usa comillas dobles "" si hay caracteres especiales.
• Para valores booleanos, usa true/false en minúsculas (no Yes/No).
• Divide archivos grandes en varios más pequeños cuando sea posible.

Conclusiones

Los archivos YAML son una herramienta que puede ser extremadamente útil, pero también son frágiles. Validar tus archivos es fundamental para evitar errores costosos.

En resumen:

1. Valida la sintaxis con herramientas como yamllint o extensiones de VS Code.
2. Prueba el archivo en su contexto (Docker, Kubernetes, OpenAPI, etc.).
3. Valida contra esquemas cuando trabajes con formatos estandarizados.
4. Automatiza la validación en CI/CD para no depender de la memoria humana.

Así, podrás trabajar con YAML sin miedo a los errores invisibles y tendrás configuraciones robustas y confiables.