Validador YAML

Por qué YAML es más difícil de lo que parece

El atractivo de YAML es que un documento sencillo casi no necesita sintaxis. El precio es que el parser tiene que deducir muchas cosas, y la mayoría de los problemas con YAML vienen de que deduce algo distinto de lo que querías decir.

La indentación es estructura, y tiene que hacerse con espacios: los tabuladores nunca han sido válidos, por eso un editor configurado para insertarlos produce errores que parecen no tener causa. Además, la indentación es relativa, no fija, así que un bloque indentado con cuatro espacios junto a un hermano indentado con dos es un error real y no una simple incoherencia de estilo.

Encima, los mismos datos pueden escribirse de varias maneras: estilo de bloque y estilo de flujo, escalares con y sin comillas, tres formas de escribir null. Nada de esto importa hasta que un valor cae en el hueco entre ellas, y entonces importa mucho.

Las trampas de los tipos implícitos

Un escalar sin comillas recibe su tipo según su forma, y esas formas se solapan con cosas que la gente escribe como texto.

Los números de versión son el clásico. 1.10 sin comillas es un float, y los float no conservan el cero final, así que se convierte en 1.1 y la versión fijada de tu dependencia pasa a apuntar a otra sin avisar. Todo lo que empieza por cero tiene el problema inverso: en YAML 1.2, 0755 es el número 755, no un permiso de archivo en octal, y hay que escribir 0o755. Las cadenas largas de dígitos - teléfonos, referencias de cuenta, identificadores - pierden los ceros iniciales y, a partir de dieciséis cifras, la precisión.

Los booleanos son el caso famoso. YAML 1.1 trataba yes, no, on, off, y y n como booleanos, y de ahí viene el "problema de Noruega": una lista de países que contiene NO se convierte en una lista que contiene false. El core de YAML 1.2 lo redujo a true y false, que es lo que sigue esta herramienta, pero mucho software sigue usando parsers 1.1 - Psych de Ruby y versiones antiguas de PyYAML, entre otros -, así que lo prudente es poner entre comillas todo lo que quieras que sea texto.

También conviene saber que null puede escribirse null, ~ o nada en absoluto, así que una clave con valor vacío es null y no una cadena vacía. Y en YAML 1.1, 22:22 se interpreta como número sexagesimal, no como una hora.

Cadenas de varias líneas

Dos indicadores de escalar de bloque cubren casi todos los casos, y elegir mal es una causa frecuente de configuraciones rotas.

La barra vertical (|) conserva los saltos de línea tal como están escritos. Es lo que quieres para un script de shell, un certificado, un archivo de configuración incrustado o cualquier cosa en la que la estructura de líneas tenga significado. El signo mayor que (>) pliega el texto: los saltos simples se convierten en espacios y las líneas en blanco en saltos, lo que viene bien para un párrafo largo que quieres partir en el código fuente sin partirlo en el valor.

Ambos admiten un indicador de chomping que controla el salto de línea final. Sin indicador se conserva exactamente uno, el signo menos (-) los elimina todos y el más (+) los conserva todos. El menos importa cuando un salto final rompería lo que consume el valor - un token, una clave, un argumento -, y el más cuando necesitas conservar los espacios exactamente.

El contenido se indenta respecto a la clave, y esa indentación se elimina del valor. Una línea más indentada que el resto conserva los espacios extra, y así un script dentro de un manifiesto mantiene su propia estructura.

Anclas, alias y claves de fusión

Un ancla marca un nodo con & y un alias lo referencia con *, lo que permite a un documento reutilizar un valor definido antes. En una configuración de CI o un archivo compose, esto es lo que elimina la repetición entre trabajos o servicios casi idénticos, y es una de las buenas razones reales para escribir YAML en lugar de JSON.

La clave de fusión, escrita <<: *base, va más allá e incorpora las claves de un mapa anclado al mapa actual para que puedas sobrescribir solo algunas. Conviene saber que no forma parte del core de YAML 1.2: es una especificación aparte que la mayoría de parsers implementa y algunos no, así que no es segura en todas partes.

Todo esto desaparece, necesariamente, al convertir a JSON. Los alias se resuelven en valores reales antes de la conversión, así que un ancla referenciada tres veces se convierte en tres copias de los datos y no en tres referencias. Los comentarios también desaparecen, porque JSON no los tiene. Convertir una configuración llena de anclas a JSON y de vuelta produce un documento que significa lo mismo y es mucho más largo; en cuanto a legibilidad, es un viaje sin retorno.

Comillas: cuándo importan y cuál usar

Un escalar sin comillas se tipa según su forma, así que poner comillas es la manera de decir que eso es texto. Las comillas simples son literales, salvo que dos comillas simples seguidas representan un apóstrofo: no se procesa ningún escape, de modo que 'C:\path\to' es exactamente esa cadena. Las comillas dobles sí procesan escapes, así que \n se convierte en un salto de línea y una barra invertida literal hay que duplicarla.

La regla que evita casi todos los problemas: usa comillas simples por defecto, comillas dobles solo cuando necesites una secuencia de escape, y entrecomilla cualquier cosa que pueda leerse como otro tipo. Eso cubre los números de versión, los valores formados solo por dígitos, cualquier cosa que empiece por cero y las palabras yes, no, on y off.

Hay unos cuantos caracteres que obligan a usar comillas allí donde aparezcan dentro de un valor: dos puntos seguidos de espacio, una almohadilla precedida de espacio y un &, *, !, %, @ o acento grave al principio. Un valor que empieza por llave o corchete inicia el estilo de flujo, así que una plantilla de Jinja o de Helm como {{ .Values.name }} tiene que ir entre comillas o el analizador la leerá como un mapeo anidado.

Los errores que rompen los archivos de Kubernetes y de CI

El primero es la indentación de los elementos de una lista. Una secuencia bajo una clave puede ir indentada o alineada con la clave, y las dos formas son válidas, pero los elementos de una misma secuencia deben coincidir entre sí. Mezclarlas dentro de un archivo que han editado varias personas produce un error cuya línea reportada suele estar en un sitio completamente distinto.

El segundo son los archivos con varios documentos. Tres guiones separan documentos, y una herramienta que solo lee el primero ignora en silencio todo lo que va después del separador: así es como un manifiesto de Kubernetes aplica el Deployment y no el Service. kubectl maneja varios documentos; muchísimos scripts que usan la función de carga por defecto del lenguaje no lo hacen, y necesitan la variante load-all.

El tercero es el valor vacío. Una clave sin nada después de los dos puntos vale null, no una cadena vacía ni un mapa vacío, de modo que un bloque de configuración que se ha comentado pero al que se le ha dejado la clave se interpreta como un null donde el consumidor esperaba un objeto. Los nulls y las cadenas vacías se comportan de forma distinta en todos los sistemas de plantillas construidos sobre YAML.

Validar YAML contra un esquema

Un analizador te dice que el archivo es sintácticamente válido. Un esquema te dice que el contenido tiene sentido y, para cualquier cosa operativa, esa es la comprobación más útil. Como YAML se corresponde con el mismo modelo de datos que JSON, JSON Schema funciona directamente sobre él, que es lo que usan la mayoría de los editores para ofrecer autocompletado y errores en línea en un manifiesto de Kubernetes o en un archivo de GitHub Actions.

En una canalización, los validadores especializados llegan más lejos que un esquema genérico: kubeconform comprueba los manifiestos contra los esquemas de la API de Kubernetes de una versión concreta, yamllint impone un estilo y detecta problemas de indentación y claves duplicadas, y la mayoría de los sistemas de CI permiten validar su propio archivo de configuración en local antes de hacer push.

Las claves duplicadas merecen mención aparte. La mayoría de los analizadores las aceptan y se quedan con la última, descartando la primera en silencio, así que un valor definido dos veces en un archivo largo parece que simplemente se ignora. Los linters lo señalan; el entorno de ejecución del lenguaje, normalmente, no.

Plantillas sobre YAML, y por qué duele

Helm, Ansible y la mayoría de los sistemas de CI generan YAML a partir de plantillas, lo que significa un lenguaje de plantillas de texto produciendo un formato sensible a los espacios. Los resultados son predecibles: un valor insertado con la indentación equivocada, una cadena de varias líneas que aplasta un bloque, un condicional que elimina una línea y deja una clave colgando.

Dos hábitos alivian el dolor. Renderiza antes de aplicar - helm template, o la simulación equivalente - y lee la salida como YAML en lugar de fiarte de la plantilla. Y usa los ayudantes de indentación que ofrece la herramienta, como nindent en Helm, en vez de contar espacios a mano dentro de la plantilla.

La alternativa de fondo es generar YAML a partir de datos y no de texto: construye una estructura en un lenguaje de verdad y serialízala, de modo que la indentación sea problema del serializador. Para eso existen CDK8s, Pulumi y varios lenguajes de configuración como CUE y Dhall, y así se elimina una categoría entera de fallos.

Secretos, comentarios y qué sobrevive a la conversión

Los archivos de configuración en YAML son el sitio donde más a menudo terminan los secretos dentro de un repositorio, normalmente como un valor que alguien pensaba quitar antes de hacer el commit. Mantenerlos fuera es una decisión de flujo de trabajo - variables de entorno, un gestor de secretos, o archivos cifrados con SOPS o sealed secrets - y vale la pena escanear el repositorio una vez para ver qué hay ya dentro, recordando que el historial conserva todo lo que alguna vez se ha confirmado.

Los comentarios son la otra cosa que conviene proteger. Son la única documentación que tienen muchos archivos de configuración, y no sobreviven a una conversión a JSON ni a un viaje de ida y vuelta por un programa que carga el archivo y lo vuelve a serializar. Existen herramientas que editan YAML en su sitio conservando los comentarios - ruamel.yaml en Python, yq para ediciones desde la línea de comandos - y son la elección correcta para cambios automatizados sobre un archivo que mantienen personas.

Lo mismo pasa con las anclas. Al convertir a JSON, cada alias se expande en una copia, así que una configuración construida en torno a bloques compartidos vuelve mucho más larga y sin la estructura que la hacía mantenible. Para una máquina significa lo mismo, y para la siguiente persona que la edite, bastante menos.