Indentación YAML: espacios, tabuladores y errores frecuentes

Respuesta breve

YAML usa espacios para definir la estructura de mapas y secuencias de bloque. Alinea las claves y los guiones hermanos e indenta los mapas anidados más que su padre. Los tabuladores no sirven para esa sangría. Una secuencia que sea el valor de una clave también puede alinear sus guiones con ella; más abajo se muestra ese estilo válido.

Ejemplo correcto

En este documento se utilizan dos espacios por nivel:

servicio:
  nombre: api
  puertos:
    - 8080
    - 8443
  salud:
    ruta: /health

nombre, puertos y salud son propiedades hermanas. Los dos números son elementos de la misma secuencia y ruta pertenece al mapa salud. YAML no obliga a escoger exactamente dos espacios, pero sí a mantener una estructura coherente.

El conversor YAML a JSON permite comprobar la estructura resuelta. Si un bloque aparece dentro de una propiedad distinta de la esperada, compara las columnas del texto original antes de convertirlo.

Un espacio cambia el árbol

Este fragmento no mantiene el mismo nivel para los dos puertos:

servicio:
  puertos:
    - 8080
   - 8443

El segundo guion empieza una columna antes. Este documento concreto es inválido: el conversor señala la línea 4, columna 4. Añade un espacio antes de ese guion para que ambos comiencen en la columna 5:

servicio:
  puertos:
    - 8080
    - 8443

El array servicio.puertos debe contener los dos números 8080 y 8443, no una cadena ni una segunda propiedad.

YAML válido con un padre incorrecto

Este documento se analiza sin errores, pero timeout pertenece a salud, no a servicio:

servicio:
  salud:
    ruta: /health
    timeout: 30

Si la aplicación espera servicio.timeout, mueve timeout dos espacios a la izquierda, alineándolo con salud. El JSON corregido es:

{
  "servicio": {
    "salud": { "ruta": "/health" },
    "timeout": 30
  }
}

Una lista válida sin sangría adicional

YAML permite que una secuencia usada como valor de una clave se alinee con ella:

puertos:
- 8080
- 8443

Sigue significando {"puertos":[8080,8443]}. También es válido indentar ambos guiones dos espacios. Escoge un estilo legible; no marques la versión alineada como error de sintaxis solo por tener un aspecto distinto.

Por qué no debes indentar con tabs

La sección de indentación de YAML 1.2.2 excluye los tabuladores de los caracteres usados para indentar, porque su ancho visual depende del editor. Configura el editor para insertar espacios al pulsar Tab y activa la visualización de caracteres invisibles.

Un tabulador sí puede formar parte del contenido de una cadena entre comillas o de ciertos bloques de texto después de la sangría requerida. La regla importante es que no determine el nivel estructural.

Lista de diagnóstico

1. Muestra espacios y tabs en el editor.
2. Localiza la línea señalada y revisa también la línea anterior.
3. Compara la columna inicial de todos los elementos hermanos.
4. Confirma que cada - de una misma lista está alineado.
5. Sustituye tabs de indentación por espacios, no tabs que pertenezcan al dato.
6. Convierte de nuevo y verifica la estructura JSON, no solo que desaparezca el error.

Errores frecuentes

• Alinear el texto por aspecto sin comprobar las columnas reales.
• Mezclar dos y cuatro espacios dentro del mismo conjunto de hermanos.
• Indentar una propiedad bajo el último elemento de una lista por accidente.
• Corregir únicamente la línea del diagnóstico cuando el bloque padre es el que tiene el nivel equivocado.
• Reindentar automáticamente un archivo sin revisar cadenas multilínea.

Una vez corregida la sintaxis, compara las claves y arrays obtenidos con el modelo esperado. Que el YAML pueda analizarse no garantiza que su jerarquía sea la correcta.