Sintaxis de YAML

Tras un pequeño debate con un compañero que prefería utilizar las "cajitas" de los pipelines de Azure DevOps frente a emplear ficheros con YAML. Él defendía la complejidad de escribir e interpretar el código YAML, por lo que me he lanzado a escribir este post que explica de una forma muy básica cómo se utiliza este lenguaje.

Definición

YAML se define como un lenguaje fácil de interpretar para el ser humano, es una serialización de datos estructurados de una forma muy sencilla. A diferencia de XML o JSON, YAML no es un lenguaje de marcado.

XML

Por ejemplo, si queremos representar una colección de datos en formato XML, haríamos algo similar a esto:

<countries>
    <country>
        <name>Spain</name>
        <language>es-ES</language>
        <population>46.94 million</population>
    </country>
    <country>
        <name>United Kingdom</name>
        <language>en-UK</language>
        <population>66.65 million</population>
    </country>
</countries>

XML está claro que es un lenguaje que está muy arraigado, lo podemos encontrar en el estándar de las fuentes RSS, si ya llevas años trabajando con él, resulta fácil de leer, siempre y cuando esté bien formateado con su indentación y sus saltos de carro, porque si no es así, resulta imposible saber que contiene.

JSON

Siguiendo con el ejemplo del XML, la misma colección de datos, pero en JSON, haríamos lo siguiente:

{
    countries: [
        {
            name: "Spain",
            language: "es-ES",
            population: "49.94 million"
        },
        {
            name: "United Kingdom",
            language: "en-UK",
            population: "66.65 million"
        }
    ]
}

JSON es ideal para agilizar las comunicaciones, tiene un mejor rendimiento que los ficheros XML porque consumen menos memoria. Hoy por hoy, nadie contempla la posibilidad de crear un servicio que no devuelva sus datos en este formato, aunque algunos como el API REST de SharePoint Online, aún se resisten y devuelven sus datos de forma predeterminada en formato XML salvo que lo indiques en la llamada que los devuelve en formato JSON.

Al igual que XML, si estás familiarizado con este formato y si se encuentra bien indentado, con sus saltos de carro, puede resultar fácil de interpretar para el ser humano, si no es así, es muy complicado de leer. A la hora de escribirlo hay que tener mucho cuidado con las llaves, que estén bien jerarquizadas y por supuesto, bien cerradas.

YAML

En cambio, si el mismo ejemplo lo escribimos en YAML, simplificamos el contenido notablemente.

countries:
  - name: 'Spain'
    population: '49.94 million'
    language: 'es-ES'
  - name: 'United Kingdom'
    language: 'en-UK'
    population: '66.65 million'

Nos encontramos con una colección, donde vemos listados dos países, y para cada país se indica el nombre, el lenguaje y la población que tiene. Se lee fácilmente, no requiere realizar ningún tipo de operación adicional para formatear el texto y poder entenderlo.

Sintaxis

Lo primero que necesitamos entender es que los espacios en el YAML son fundamentales, por lo que no podemos añadir o eliminar espacios aleatoriamente. Esto quiere decir, que un espacio fuera de lugar puede alterar la estructura o invalidar el contenido, por ejemplo:

countries:
    #Error de sintaxis falta un espacio entre la clave name y su valor
  - name:'Spain'
    language: 'es-ES'
    population: '49.94 million'

Si la indentación no es correcta puede ocurrir dos cosas, la primera que invalide todo el YAML, y la segunda que deje inconsistente la información.

#Language es un valor independiente y no una propiedad de country  
country:
   name: 'Spain'
language: 'es-ES'

El idioma quedaría como un elemento escalar independiente, no sería un atributo de país, el fichero sería válido, pero el contenido sería erróneo. Para apreciar el error en este ejemplo, en formato JSON tendríamos esto:

{
    "country":{
        "name": "Spain"
    },
    "language": "es-ES"
}

Elementos

Los elementos básicos que podemos encontrar en un YAML son los siguientes:

Objetos
Escalares
Colecciones
Comentarios
Delimitadores

Objetos

Un objeto es un elemento compuesto por uno o varios escalares o colecciones.

planet:
  name: 'Earth'
  population: '7.674 billion'
  countries:
  - name: 'Spain'
    population: '49.94 million'
    language: 'es-ES'
  - name: 'United Kingdom'
    language: 'en-UK'
    population: '66.65 million'

En este ejemplo vemos un objeto de tipo Planeta, con varias propiedades entre la que destaca una colección de países.

Escalares

Se trata de pares de clave / valor. Es decir, son entradas de un diccionario, su notación:

key: value

Las claves no se escriben nunca entre comillas, y los valores se pueden escribir con y sin comillas. Por convención es recomendable utilizar comillas para literales, y el resto de los valores primitivos sin estas, pero esto no deja de ser una recomendación.

name: 'Juan'
last name: 'García González'
age: 20
hired: true
bio: null

Las claves se separan de los valores con :, esto permite que una clave pueda contener espacios. El caso de los apellidos del anterior YAML, se podría convertir tal como está a JSON, en cambio en XML requeriría realizar una modificación a esa clave para adaptarla al estándar del marcado que no soporta espacios en el nombre de los elementos.

Colecciones

Una colección es un conjunto de elementos escalares o colecciones anidadas.

countries:
  - name: 'Spain'
    population: '49.94 million'
    languages:
      - 'es-ES'
      - 'es-GL'
      - 'es-EU'
      - 'es-CA'
  - name: 'United Kingdom'
    population: '66.65 million'
    languages:
      - 'en-UK'

Cada elemento de la enumeración se separa por un -, este carácter indica que se trata de un nuevo valor en la colección, y cada escalar dentro de su indentación se trata como una propiedad de ese objeto.

La propiedad lenguajes es una colección anidada dentro del elemento país, que a modo de ejemplo almacena una colección de elementos sin clave, es decir, se trataría de un array de literales.

Comentarios

YAML, al igual que otros lenguajes, tiene su forma de representar texto como comentarios, estos se establecen mediante el símbolo # al inicio del texto con el comentario.

#Name (max length: 20 chars)
name: 'Juan'
#Last Name (max length: 50 chars)
last name: 'García González'
#Age (Integer)
age: 20 #Mandatory
#Hired (Boolean)
hired: true #Mandatory
#Bio (max length: 500 chars)
bio: null

Como en cualquier otro lenguaje, los comentarios ensucian mucho y deberían evitarse en la medida de lo posible.

Delimitadores

Aunque se trata de un elemento opcional, ayudan a establecer los límites de un documento en este formato.

---: Inicio del documento
...: Fin del documento

---
countries:
  - name: 'Spain'
    population: '49.94 million'
    languages:
      - 'es-ES'
      - 'es-GL'
      - 'es-EU'
      - 'es-CA'
  - name: 'United Kingdom'
    population: '66.65 million'
    languages:
      - 'en-UK'
...

Conclusiones

A pesar de lo fuera de lo común que es este lenguaje respecto a los que estamos acostumbrados, es bastante sencillo de utilizar, y que se está estandarizando muchísimo, de hecho es la base para crear ficheros de imágenes en Docker, definir GitHub Actions, como pipelines de Azure DevOps o pods de Kubernetes, entre otros.

Además de esta sintaxis básica, YAML soporta otros modificadores que permiten jugar con los saltos de línea y espacios, para escribir, si es necesario, contenido de una forma más efectiva y clara.