Indentación YAML: espacios, tabuladores y errores frecuentes

Respuesta breve

YAML usa espacios de indentación para expresar qué valores pertenecen a cada mapa o secuencia. Los elementos hermanos deben comenzar en la misma columna y un hijo debe quedar más indentado que su padre. Un tabulador no puede sustituir los espacios que forman esa sangría.

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. Según el contexto, el analizador producirá un error o entenderá una estructura que no era la pretendida. El problema no es visual: la columna forma parte de la sintaxis.

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.