Cómo validar YAML antes de usarlo en Docker o CI/CD

Guía · Beauttytext

Un error de YAML en un docker-compose.yml o en un workflow de GitHub Actions no siempre da un mensaje de error claro — a veces simplemente el pipeline falla, o un servicio arranca con una configuración distinta a la que esperabas. Validar el YAML antes de commitearlo evita ese tipo de sorpresas.

Por qué YAML falla en silencio

A diferencia de JSON, YAML usa la indentación (espacios, nunca tabs) para representar la jerarquía del documento. Un espacio de más o de menos en una línea no siempre produce un error de sintaxis: a veces produce un documento válido pero con una estructura distinta a la que querías, y eso es más difícil de detectar que un error evidente.

Los errores más comunes

1. Mezclar tabs y espacios

YAML no permite tabs para indentar. Un editor que inserte un tab en vez de espacios (algo fácil de que pase sin darte cuenta) invalida el documento.

2. Indentación inconsistente entre hermanos

services:
  web:
    image: nginx
   ports:
    - "80:80"

El ports tiene un espacio menos que image — ya no es un hijo del mismo nivel que web, y el parser lo interpretará de forma distinta a la esperada.

3. Dos puntos sin espacio después

environment:
  KEY:value

YAML necesita un espacio después de los dos puntos (KEY: value); sin él, se interpreta como texto plano en vez de como par clave-valor.

4. Claves duplicadas

Si una clave aparece dos veces en el mismo nivel, la mayoría de parsers se queda silenciosamente con la última y descarta la primera, sin avisar — un error especialmente peligroso porque no rompe la sintaxis.

Ejemplo: de YAML roto a YAML válido

Antes (indentación inconsistente y dos puntos sin espacio):

services:
  web:
   image:nginx
    ports:
    - "80:80"

Después:

services:
  web:
    image: nginx
    ports:
      - "80:80"

Validar antes de hacer commit

Un validador de YAML que use un parser real (no solo comprobación visual) te indica la línea y columna exactas del problema antes de que llegue a tu pipeline de CI/CD, donde un fallo cuesta más tiempo detectar y corregir. El YAML Formatter de Beauttytext formatea, valida y convierte a JSON al instante, en tu navegador — sin subir tu configuración a ningún servidor externo.