Fundamentos de YAML

La indentación es la sintaxis

En YAML, los espacios en blanco no son decoración — son toda la estructura. Un mapeo es una clave, dos puntos, un espacio y un valor; un valor anidado se escribe en la línea siguiente, con más indentación, y dos líneas con la misma indentación son hermanas. Los tabuladores están prohibidos sin matices: la especificación no puede decidir cuánto mide un tabulador, así que los parsers los rechazan en lugar de adivinar. Los editores siguen insertando tabuladores al copiar y pegar, y por eso hay tantos archivos que parecen perfectos y se niegan a parsearse.

La convención es dos espacios por nivel. Cuatro o seis son igual de válidos — la especificación solo prohíbe los tabuladores — pero dos es lo que usan Kubernetes y Compose, lo que espera cualquier linter y lo que evita que los manifiestos profundos se salgan por la derecha. Mezclar anchuras dentro de un archivo es así como nacen los errores de indentación, así que elige dos y deja que el editor lo imponga.

• Un nivel = cualquier número fijo de espacios; dos es la convención.
• Los tabuladores en la indentación los rechazan los parsers; no se convierten.
• Un elemento de secuencia puede quedar a la altura de la indentación de su clave padre — el guion es la marca.
• Los valores también pueden escribirse en línea con estilo de flujo: ports: [8080].

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

Los escalares y el problema de Noruega

Los valores entre comillas son cadenas, siempre. Los valores sin comillas reciben un tipo por inferencia, y la inferencia es de donde viene la reputación de YAML: un 8080 suelto se convierte en el número 8080 y un valor vacío se convierte en null, lo cual ayuda — hasta que la inferencia asigna un tipo a algo que tú querías como texto, como un código de país o una cadena de versión.

El fallo clásico es una lista de códigos de país ISO en la que NO — Noruega — se parsea como el booleano false: el problema de Noruega, gracioso hasta que desactiva en silencio un flag de despliegue. La versión 1.1 fue mucho más lejos, como muestra la tabla. El esquema central de 1.2 solo resuelve true y false como booleanos y lee el resto de la tabla de abajo como cadenas de texto o números decimales — pero como muchísimo software desplegado sigue aplicando las reglas de 1.1, el hábito defensivo es entrecomillar todo lo que deba seguir siendo una cadena.

Comillas y escalares en bloque

YAML ofrece tres formas de escribir una cadena. Sin comillas es la opción por defecto y vale para la mayoría de los valores. Las comillas simples son literales — el único escape es duplicar la comilla ('it''s fine'). Las comillas dobles admiten escapes con barra invertida como \n y \t, el estilo que usa JSON. La regla defensiva sigue en pie: si un valor contiene algo que pudiera confundirse con estructura — dos puntos, signos #, palabras reservadas — entrecomíllalo a propósito.

El texto multilínea usa escalares en bloque. Un bloque literal, escrito con |, conserva cada salto de línea tal como se escribe — la forma adecuada para scripts de shell y certificados. Un bloque plegado, escrito con >, une las líneas en un solo párrafo fluido — la forma adecuada para una descripción larga. Ambos aceptan un indicador de recorte: |- elimina el salto de línea final, |+ conserva todos los del final y un | normal conserva exactamente uno.

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

Anclas, alias y reutilización

YAML permite que un nodo lleve un nombre que otros nodos referencian. Escribe &name después de una clave para anclar su valor; escribe *name en cualquier otro sitio para crear un alias, y el parser sustituye una copia del nodo anclado. Varios jobs que comparten una política de reintentos apuntan así a una sola definición, y el cambio se aplica una sola vez.

Dos extensiones se apoyan en este mecanismo. Las claves de fusión, escritas <<: *name, insertan todas las claves de un mapeo anclado en el actual — algo común en archivos de Compose y Ansible, y una convención de la era 1.1 que nunca entró en la gramática central de 1.2. Las anclas también pueden abusarse: alias anidados dentro de alias permiten que diez definiciones se expandan a un millón de nodos — el ataque billion laughs — así que los parsers en los que confías presupuestan la expansión e informan del límite en lugar de quedarse colgados.

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

Comentarios y múltiples documentos

Los comentarios empiezan con # y llegan hasta el final de la línea; una # dentro de una cadena entre comillas no cuenta. Esta es la mayor ventaja ergonómica de YAML frente a JSON, que eliminó los comentarios a propósito, y la razón por la que la configuración mantenida por personas gravita hacia aquí: el archivo se explica a sí mismo en línea, y en las revisiones se cita una línea y su comentario en el mismo fragmento del diff.

Un archivo también puede contener varios documentos, separados por líneas de tres guiones; un --- inicial es la marca opcional de comienzo y ... cierra un documento. Así es como un mismo artefacto lleva una configuración de staging y una de producción lado a lado. Los convertidores de este sitio parsean todos los documentos y operan sobre el último, igual que el comportamiento habitual de las CLI.

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

Lo que aceptan los convertidores de este sitio

Todo parser de YAML es el parser de un subconjunto — la gramática completa de 1.2 es famosamente enorme — y un convertidor gana confianza declarando su subconjunto en lugar de dejarte descubrirlo a base de fallos. La librería YAML de este sitio implementa el esquema central de 1.2 sobre las construcciones de bloque y de flujo que aparecen en archivos de configuración reales, con límites deliberados donde la especificación permite trabajo ilimitado. La tabla es el contrato.