Cómo escribir listas y objetos en YAML sin equivocarse de nivel

Respuesta breve

Una lista YAML es una secuencia cuyos elementos empiezan con -; un objeto es un mapa de claves y valores separados por :. Para crear una lista de objetos, alinea todos los guiones y coloca las propiedades adicionales de cada elemento al mismo nivel que la primera clave situada después del guion.

Lista de valores simples

puertos:
  - 80
  - 443
  - 8080

La clave puertos contiene una secuencia de tres números. Los guiones están en la misma columna porque los tres elementos son hermanos. Su equivalente JSON es:

{
  "puertos": [80, 443, 8080]
}

Lista de objetos

servidores:
  - nombre: api-1
    ip: 192.0.2.10
    activo: true
  - nombre: api-2
    ip: 192.0.2.11
    activo: false

Cada guion abre un elemento de la secuencia. nombre, ip y activo forman el mapa del mismo servidor. El segundo guion vuelve a la columna del primero y empieza el siguiente elemento.

El conversor YAML a JSON muestra dos objetos dentro del array servidores. Verifica siempre el resultado resuelto: un YAML que se analiza puede representar un árbol distinto del que parecía a simple vista.

El error de nivel más habitual

Este fragmento mueve activo fuera de la estructura esperada:

servidores:
  - nombre: api-1
    ip: 192.0.2.10
  activo: true

Este YAML es inválido, no un objeto válido con una propiedad desplazada: una entrada de mapa no puede aparecer junto a los guiones de la secuencia en ese nivel. Si activo pertenece al servidor, añade dos espacios antes de la clave:

servidores:
  - nombre: api-1
    ip: 192.0.2.10
    activo: true

El JSON corregido contiene un servidor con tres propiedades:

{
  "servidores": [{ "nombre": "api-1", "ip": "192.0.2.10", "activo": true }]
}

Si activo pertenece al documento completo, muévelo hasta el margen izquierdo, alineado con servidores. También será válido, pero la propiedad quedará en la raíz, fuera del array. Elige según el esquema de la aplicación, no solo por conseguir que desaparezca el error.

Mapas que contienen listas y listas que contienen mapas

Las estructuras pueden alternarse dentro de los límites del analizador y de la aplicación:

servicio:
  nombre: api
  destinos:
    - host: db-1
      roles:
        - lectura
        - escritura
    - host: db-2
      roles:
        - lectura

Lee el documento desde fuera hacia dentro: servicio es un mapa, destinos es una lista, cada destino es un mapa y roles vuelve a ser una lista.

Lista de comprobación

1. Identifica el tipo esperado de cada nodo: mapa, secuencia o escalar.
2. Alinea todos los guiones que pertenecen a la misma lista.
3. Alinea las propiedades hermanas de cada mapa.
4. No uses tabs para definir la indentación.
5. Convierte el ejemplo a JSON y cuenta objetos, arrays y niveles.
6. Compara el árbol resultante con el esquema de la aplicación.

La sección 8.2 de YAML 1.2.2 define las secuencias de bloque mediante el indicador - y los mapas mediante parejas clave/valor. La indentación determina a qué colección pertenece cada nodo, así que una columna distinta cambia la estructura.