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

El problema no es solo estético. activo ya no está alineado con las propiedades del objeto y el procesador puede rechazar el documento porque en ese punto esperaba otro elemento de la secuencia.

Una variante también peligrosa es alinear una propiedad con el guion:

servidores:
  - nombre: api-1
  ip: 192.0.2.10

ip no pertenece al objeto iniciado después del guion. Compara columnas, no el número aparente de espacios entre palabras.

Mapas que contienen listas y listas que contienen mapas

Las estructuras pueden anidarse sin un límite conceptual especial:

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.