Validador YAML — Corrige errores YAML antes de romper tu despliegue

El despliegue que me enseñó a validar primero

Era un viernes por la tarde — el peor momento posible para que esto ocurriera. Un despliegue de Kubernetes había estado en revisión durante dos días, y después de que llegó la aprobación final, el comando kubectl apply escupió un error que paró todo:

error: error parsing deployment.yaml: error converting YAML to JSON: yaml: line 34: mapping values are not allowed in this context

Línea 34. En un manifiesto de 200 líneas. El culpable resultó ser esto:

env:
  - name: DATABASE_URL
    value: postgres://user:password@host:5432/db

Se ve bien, ¿verdad? Incorrecto. Los dos puntos en la cadena de valor — user:password — se estaban interpretando parcialmente como sintaxis de mapeo YAML. La solución fue trivial:

env:
  - name: DATABASE_URL
    value: "postgres://user:password@host:5432/db"

Un par de comillas. Treinta minutos de depuración. La lección: valida tu YAML antes de que toque algo importante.

---

Por qué YAML es genuinamente complicado

YAML tiene un problema de reputación. Parece simple — sin corchetes, sin llaves, solo pares clave-valor indentados. Esa simplicidad es real, pero viene con un coste oculto: las reglas de YAML son sorprendentemente complejas de razonar, especialmente en casos extremos.

Los espacios en blanco son sintaxis. En la mayoría de los lenguajes, los espacios en blanco son decorativos. En YAML, el número de espacios antes de una clave define su posición en el árbol del documento. Dos espacios significa un nivel de anidamiento; cuatro significa dos. Si lo haces mal, el parser o bien lanza un error o silenciosamente crea una estructura diferente a la que pretendías. El caso "silenciosamente crea una estructura diferente" es el peligroso.

Nunca tabulaciones. Esto pilla a la gente constantemente. Tu editor puede insertar tabulaciones cuando presionas la tecla Tab, podrías pegar YAML de un post de blog que usaba tabulaciones, o podrías heredar una config de alguien cuyo editor tenía configuraciones diferentes. Los parsers YAML rechazarán las tabulaciones usadas para indentación con un error como found character that cannot start any token.

La inferencia de tipos es agresiva. YAML intenta ser útil adivinando tipos. Esto crea algunos escollos famosos:

# Estos NO son cadenas en YAML 1.1 (la versión que usan la mayoría de las herramientas)
version: 1.0      # float, no cadena
enabled: yes      # booleano true, no la cadena "yes"
id: 08            # octal 8... o un error de parseo
country: NO       # booleano false (¡el código ISO de Noruega!)

Si necesitas que sean cadenas, debes ponerlas entre comillas. Siempre.

Las cadenas multilínea no son obvias. YAML tiene dos estilos de escalar multilínea — bloque literal (|) y bloque plegado (>). El literal preserva los saltos de línea; el plegado convierte los saltos de línea simples en espacios.

---

Los errores YAML más comunes (con ejemplos)

1. Cadenas sin comillas que contienen dos puntos

# ROTO — los dos puntos crean un mapeo implícito
message: Error: connection refused

# CORREGIDO
message: "Error: connection refused"

2. Tabulaciones en lugar de espacios

# ROTO (tabulación antes de "name")
server:
	name: prod-01   # carácter de tabulación aquí — dará error

# CORREGIDO (espacios)
server:
  name: prod-01

3. Indentación inconsistente

# ROTO — "port" está indentado 4 espacios mientras "host" usa 2
database:
  host: localhost
    port: 5432    # incorrecto — esto hace que "port" sea hijo de "host"

# CORREGIDO
database:
  host: localhost
  port: 5432

4. Caracteres especiales sin comillas

# ROTO — # comienza un comentario, así que "value" se pierde
description: This is important # not a comment here

# En realidad está bien — los comentarios en línea son YAML válido
# Pero si quieres el # en el valor:
description: "This is important # still part of the string"

5. Claves duplicadas

# ROTO — el segundo "host" sobrescribe silenciosamente al primero en la mayoría de parsers
database:
  host: localhost
  port: 5432
  host: prod.example.com   # duplicado — malo

6. Valores booleanos y null incorrectos

# Todos estos son booleano true en YAML 1.1:
enabled: true
enabled: True
enabled: yes
enabled: on

# Todos estos son null:
value: ~
value: null
value: Null

# Si quieres la cadena "yes" o "null", ponla entre comillas:
status: "yes"
type: "null"

7. Errores de ancla/alias

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults    # clave de fusión — válido pero confuso
  timeout: 60      # sobreescribe el valor del ancla

staging:
  <<: *defaults
  timeout: 15

---

Cómo usar el validador YAML

El validador YAML en toolboxhubs.com está diseñado para el flujo de trabajo donde capturas errores antes de que lleguen a tu pipeline.

Paso 1 — Pegar el YAML. Copia el contenido completo de tu archivo de configuración — docker-compose.yml, .github/workflows/deploy.yml, values.yaml, lo que estés trabajando — y pégalo en el panel de entrada.

Paso 2 — Ejecutar la validación. El validador parsea tu YAML inmediatamente y reporta el primer error de sintaxis que encuentra, incluyendo el número de línea. Corrígelo y vuelve a ejecutar.

Paso 3 — Revisar la salida parseada. Más allá de atrapar errores, el validador muestra la estructura parseada como un árbol. Aquí es donde detectas errores lógicos — quizás tu clave está en el lugar correcto sintácticamente pero en el nivel de anidamiento incorrecto.

Paso 4 — Verificar los tipos. Presta atención a si las cadenas aparecen como cadenas, los booleanos como booleanos y los números como números.

Para convertir entre formatos, el convertidor JSON a YAML gestiona las conversiones de ida y vuelta, y el formateador JSON es útil cuando trabajas con ambos formatos en el mismo proyecto.

---

YAML vs JSON — ¿Cuándo elegir cuál?

Usar YAML cuando:

• Los humanos editan el archivo regularmente (configs de CI, manifiestos de Kubernetes, playbooks de Ansible)
• Los comentarios son importantes — YAML soporta comentarios #, JSON no
• Se quiere reducir el ruido visual en estructuras anidadas
• La config es principalmente estática y no generada por máquina

Usar JSON cuando:

• El archivo es generado por código y leído por código — los humanos rara vez lo tocan
• Se necesitan garantías de tipo estrictas
• Se está trabajando con una API que espera JSON
• Se quiere el tooling más simple posible

---

YAML en herramientas específicas

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
        env:
          NODE_ENV: test
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

La sintaxis de expresión ${{ }} no es sintaxis YAML — es evaluada por Actions antes del parsing YAML.

Docker Compose

services:
  app:
    image: node:20-alpine
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    volumes:
      - ./src:/app/src:ro
    depends_on:
      db:
        condition: service_healthy

Nota "3000:3000" entre comillas — los dos puntos lo hacen necesario.

Manifiestos de Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-app:latest
          ports:
            - containerPort: 8080

El doble anidamiento spec.template.spec pilla frecuentemente a la gente. El spec interior es la especificación del Pod; el exterior es la especificación del Deployment.

Ansible

- hosts: webservers
  vars:
    deploy_path: /var/www/app
  tasks:
    - name: Copy application files
      copy:
        src: "{{ item }}"
        dest: "{{ deploy_path }}/{{ item }}"
      loop:
        - index.html
        - app.js
        - styles.css

La sintaxis de plantilla Jinja2 {{ }} necesita comillas (como se muestra con "{{ item }}") o el parser YAML de Ansible interpretará el { de apertura como un mapeo de flujo YAML.

---

Consejos para escribir YAML sin errores

1. Usar un linter, no solo un validador. Un validador te dice si el YAML es sintácticamente válido. Un linter como yamllint también impone indentación consistente, espacios al final, longitud de línea y otras reglas de estilo.

2. Configurar correctamente el editor. Configura tu editor para usar espacios (no tabulaciones) para archivos .yml y .yaml, con indentación de 2 espacios. La extensión YAML de VS Code (de Red Hat) valida sobre la marcha y valida el esquema de archivos de Kubernetes, GitHub Actions y Docker Compose automáticamente.

3. Poner cadenas entre comillas de forma defensiva. Si un valor de cadena contiene :, #, {, }, [, ], *, & o !, ponlo entre comillas. Si podría malinterpretarse como booleano o null, ponlo entre comillas.

4. Validar antes de hacer push. Añadir validación YAML a tus hooks pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [-d, relaxed]

5. Usar anclas, pero documentarlas. Las anclas reducen la duplicación pero añaden sobrecarga cognitiva. Si usas &defaults y <<: *defaults, añade un comentario explicando qué contiene el ancla y dónde se usa.

6. Cuidado con el problema de Noruega. En YAML 1.1, la cadena de dos letras NO se parsea como booleano false. El código de país ISO 3166-1 alpha-2 de Noruega es NO. Pon siempre entre comillas los códigos de país y cadenas de estado como yes/no.

7. Conocer la versión YAML de tu parser. PyYAML de Python usa 1.1 por defecto. gopkg.in/yaml.v3 de Go implementa 1.2. js-yaml de JavaScript también es 1.2 por defecto. Esto importa cuando compartes configs entre cadenas de herramientas.

---

Conclusión

YAML es el lenguaje de configuración dominante para las herramientas de infraestructura modernas — Kubernetes, GitHub Actions, Docker Compose, Ansible y la mayoría de los sistemas CI/CD están construidos alrededor de él. Eso hace que conocer sus modos de fallo sea genuinamente importante.

El flujo de trabajo práctico es simple: pega tu config en el validador YAML antes de hacer push, especialmente para cualquier cosa que toque un pipeline de despliegue. Toma diez segundos y captura la clase de errores que de otro modo te enviaría a perseguir un número de línea críptico en un manifiesto de 200 líneas un viernes por la tarde.

Para convertir configs entre formatos, JSON a YAML gestiona la conversión limpiamente, y formateador JSON es útil para validar el lado JSON de la ecuación. Adquiere el hábito de validar primero — tu yo futuro lo agradecerá.