Che cos'è YAML? Nozioni di base, sintassi e casi d'uso

Nel corso degli anni ho lavorato con innumerevoli file di configurazione, e YAML si è distinto per semplicità e leggibilità. Che si tratti di impostare workflow in Kubernetes, definire servizi in Docker o strutturare richieste API, YAML rende più gestibili configurazioni complesse. La sua struttura pulita, basata sull'indentazione, elimina il disordine di formati come XML pur rimanendo flessibile.

In questa guida ti accompagnerò attraverso sintassi, struttura, funzionalità avanzate e buone pratiche di YAML, così potrai usarlo con sicurezza. 

Che cos'è YAML?

YAML (Yet Another Markup Language / YAML Ain’t Markup Language) è un formato di serializzazione dei dati che dà priorità alla leggibilità e alla facilità d'uso. Mentre XML usa un insieme di tag annidati simili a HTML e JSON utilizza parentesi graffe e virgolette, in modo analogo ai dizionari Python, YAML è più conciso e usa l'indentazione per definire la struttura, risultando più intuitivo per le persone.

YAML supporta vari tipi di dati, tra cui scalari (stringhe, numeri, booleani), sequenze (liste) e mapping (coppie chiave-valore). È ampiamente usato in file di configurazione, automazione dell'infrastruttura e scambio di dati, soprattutto in strumenti come Kubernetes, Docker e Ansible.

Inoltre, YAML è un superset di JSON, il che significa che i file JSON validi possono essere analizzati come YAML. I file YAML hanno in genere estensione .yaml o .yml.

Puoi saperne di più su YAML anche sul suo sito web!

Sintassi e struttura di YAML

In questa sezione esploreremo i principi fondamentali della sintassi YAML, incluse le coppie chiave-valore, le liste, i dati annidati e i commenti.

Regole di sintassi di base

Ci sono alcune regole sintattiche di base per YAML: 

• L'indentazione con spazi indica la struttura, quindi evita le tabulazioni! 
• Le coppie chiave-valore seguono la struttura chiave: valore, simile ad altri linguaggi. 
• Un trattino all'inizio della riga indica un elemento di lista. 
• Usare # crea righe di commento.

# Here is an example of YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Coppie chiave-valore

YAML rappresenta i dati come coppie chiave-valore, in modo simile ai dizionari in Python. Questo spesso indica informazioni fornite a diversi file e impostazioni di configurazione. Non c'è bisogno di indicare stringhe o chiavi con virgolette; scrivi semplicemente la chiave e i valori necessari:

location: New York
country: USA
security-level: user

Liste in YAML

Le liste sono rappresentate con i trattini (-). Questo ti permette di elencare più oggetti sotto un'unica chiave. Spesso, quando lette da editor di markup, sono visualizzate come elenchi puntati.

fruits:
  - Apple
  - Banana
  - Cherry

Dati annidati

Le strutture annidate consentono di rappresentare dati gerarchici usando l'indentazione. Pensale come dizionari annidati. Usando l'indentazione, indichi quali chiavi sono sottoinsiemi di altre.

person:
  name: Alice
  details:
    age: 25
    city: London

Commenti

I commenti iniziano con # e vengono ignorati dai parser YAML. Questi commenti sono su singola riga.

# This is a comment
username: admin
password: secret

Funzionalità avanzate di YAML

YAML include funzionalità potenti come stringhe multi-linea, tipi di dato e anchor che rendono i documenti più efficienti e strutturati. In questa sezione esploreremo queste capacità con esempi pratici.

Stringhe multi-linea

YAML supporta stringhe multi-linea usando | (blocco letterale) o > (blocco piegato). 

• Il blocco letterale | crea una nuova riga \n per ogni a capo. 
• Il blocco piegato > crea una nuova riga solo per a capo consecutivi.

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

Quanto sopra si capisce meglio mostrando l'output.

• Per il | (blocco letterale):

This is a
multi-line string.

• Per il > (blocco piegato):

This is another multi-line string.

Tipi di dato in YAML

YAML supporta vari tipi di dati, incluse stringhe, numeri, booleani e valori null. Rileva automaticamente i tipi in base alla formattazione ma consente anche definizioni esplicite.

Il seguente esempio mostra l'uso dei tipi di dato di base in YAML:

string_implicit: Hello, YAML!  # No quotes needed unless necessary
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Whole numbers
float: 3.14  # Numbers with decimals

boolean_true: true
boolean_false: false

null_value: null  # Null value
null_tilde: ~  # Another way to represent null

YAML consente dichiarazioni di tipo esplicite usando !!type quando necessario:

explicit_string: !!str 123  # Forces 123 to be a string
explicit_integer: !!int "42"  # Forces "42" to be an integer
explicit_float: !!float "3.14"  # Forces "3.14" to be a float

Poiché YAML è spesso usato per dati strutturati, supporta:

• Liste (sequenze):

fruits:
  - Apple
  - Banana
  - Cherry

• Dizionari (mapping):

person:
  name: Alice
  age: 30
  is_student: false

Anchor e alias

YAML ti permette di definire valori riutilizzabili usando le anchor (&) e di farvi riferimento in seguito usando gli alias (*). Questo aiuta a ridurre la ridondanza nei file di configurazione, rendendoli più puliti e facili da mantenere.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Reuses the retries value from defaults

La sintassi <<: consente di unire coppie chiave-valore da un'anchor a un altro mapping. Se una chiave esiste in entrambi, il nuovo valore sovrascrive l'originale.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Merges all key-value pairs from default_settings
  host: example.com  # This key is added to the merged data

Questa è la struttura finale risolta:

server1:
  retries: 3
  timeout: 30
  host: example.com

Anchor e alias sono particolarmente utili in file di configurazione di grandi dimensioni, dove ripetere manualmente i valori sarebbe inefficiente. Aiutano a mantenere i file YAML DRY (Don't Repeat Yourself) e a rendere più semplici gli aggiornamenti.

Casi d'uso comuni per YAML

YAML è ampiamente usato nello sviluppo software, nell'automazione dell'infrastruttura e nella gestione delle API. La sua sintassi leggibile lo rende un formato preferito per file di configurazione, serializzazione dei dati e Infrastructure as Code (IaC). Vediamo le sue applicazioni più comuni.

File di configurazione

YAML è ampiamente usato per la configurazione in applicazioni come Docker Compose, Kubernetes e pipeline CI/CD. La sua facilità di comprensione permette a chiunque di prendere i file YAML di configurazione Docker e capire cosa sta succedendo.

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80

La leggibilità di YAML e il supporto per anchor e alias aiutano a ridurre le ripetizioni, rendendolo più manutenibile di JSON o XML.

Scopri di più su YAML e sul suo utilizzo in Docker in this intermediate Docker course.

Serializzazione e trasferimento dati

YAML è usato per serializzare dati per API e strumenti di gestione della configurazione, convertendo strutture dati complesse in un formato leggibile dalle persone e facilmente analizzabile dalle macchine. 

Per esempio, un corpo di richiesta API formattato in YAML:

user:
  id: 123
  name: "John Doe"
  email: "johndoe@example.com"
  active: true

La struttura basata su indentazione di YAML elimina la sintassi superflua, rendendolo leggero, leggibile e facile da modificare rispetto a JSON.

Infrastructure as Code (IaC)

Strumenti di gestione della configurazione come Ansible e Kubernetes sfruttano YAML per definire stati di sistema, automatizzare processi e garantire coerenza tra ambienti.

• In Ansible, YAML è usato per scrivere playbook che definiscono stati di sistema, task e dipendenze, garantendo che i componenti dell'infrastruttura siano configurati in modo coerente. 
• Kubernetes utilizza manifest YAML per definire risorse come pod, servizi e deployment, abilitando l'orchestrazione automatizzata di applicazioni containerizzate.

Ecco un esempio di configurazione di un Pod Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app-container
      image: my-app:latest
      ports:
        - containerPort: 8080

Scopri di più su come YAML è usato in Kubernetes in questo corso Introduzione a Kubernetes.

Documentazione delle API

Specifiche API come OpenAPI e Swagger usano YAML per definire endpoint e strutture dati in modo facile da leggere. YAML viene usato per delineare metodi API, parametri di richiesta, formati di risposta e metodi di autenticazione.

Ecco un esempio di specifica OpenAPI in YAML:

openapi: 3.0.0
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        "200":
          description: Successful response

Le specifiche OpenAPI, ad esempio, usano YAML per documentare le API REST. Questo consente di fornire un chiaro blueprint per generare SDK client, documentazione API interattiva e test automatizzati. Questo formato strutturato garantisce coerenza tra implementazioni API.

Lavorare con i file YAML

YAML è ampiamente usato per file di configurazione, automazione e serializzazione dei dati, ma poiché si basa sull'indentazione, la formattazione corretta è cruciale. Ecco come leggere, scrivere, validare e modificare YAML in modo efficace.

Lettura e scrittura di YAML in Python

La libreria Python PyYAML può analizzare e generare YAML.

Immagina di avere il seguente file YAML di configurazione:

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Ecco come puoi lavorare con il tuo file di configurazione in Python:

import yaml

# Load YAML data
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load prevents arbitrary code execution

# Modify data (optional)
data["database"]["user"] = "new_user"

# Write YAML data
with open("output.yaml", "w") as file:
    yaml.dump(data, file, default_flow_style=False)

Se ti interessa lavorare con dati JSON in Python, dai un'occhiata al comprehensive tutorial su Python e JSON.

Validazione dei file YAML

Per garantire la struttura corretta, puoi usare strumenti per verificare tab al posto degli spazi o problemi strani come caratteri ripetuti, errori di sintassi e spazi finali.

Ecco alcuni validator YAML popolari:

• Strumento CLI: yamllint (linter basato su Python)
• Validator online: YAML Lint, YAML Validator di JSON Formatter

Modifica di YAML

Puoi scrivere e modificare YAML in qualsiasi editor di testo, ma strumenti di linting ed evidenziazione della sintassi ne migliorano la leggibilità.

Alcuni dei miei editor preferiti:

• VS Code (con plugin YAML)
• PyCharm (supporto integrato)
• Sublime Text (con evidenziazione sintassi YAML)

Errori comuni da evitare in YAML

Nonostante la sua semplicità, è ancora facile incorrere in problemi e refusi quando si lavora con YAML. Questa sezione discute questi errori e fornisce buone pratiche per scrivere file puliti e corretti. È anche il motivo per cui consiglio di usare un linter o un editor di testo!

Mischiare tab e spazi

YAML si basa sugli spazi per l'indentazione: non mischiare mai spazi e tabulazioni. Le tabulazioni romperanno semplicemente il tuo script YAML. È una scelta deliberata: sistemi diversi interpretano le tab in modo differente e, per ridurre l'impatto, si preferiscono gli spazi.

Indentazione errata

Assicurati che l'indentazione sia coerente per evitare errori di parsing. Poiché le indentazioni sono l'unico metodo di YAML per indicare la gerarchia, un parsing improprio può causare problemi con il tuo codice. È facile finire per annidare una coppia key: value nel punto sbagliato, quindi tieni d'occhio le indentazioni!

Dimenticare le virgolette per i caratteri speciali

Usa le virgolette per stringhe che contengono caratteri speciali o spazi. Elementi come backslash, virgole, punti esclamativi e così via richiedono le virgolette per essere letti come stringhe.

path: "/home/user/documents"
message: "Hello, World!"

Usando una corretta validazione, un editing strutturato e PyYAML di Python, puoi lavorare in modo efficiente con i file YAML evitando gli errori più comuni.

Conclusione

YAML è un formato potente ma semplice, ampiamente usato in configurazione, serializzazione dei dati e automazione dell'infrastruttura. Comprendendone sintassi, struttura e buone pratiche, puoi lavorare in modo efficiente con YAML in varie applicazioni.

Se vuoi applicare YAML in scenari reali:

• Scopri come YAML è usato nei workflow CI/CD con questo corso CI/CD per il Machine Learning.
• Esplora come le API usano YAML nelle loro specifiche in questo corso Introduzione alle API in Python.
• Approfondisci containerizzazione e automazione dell'infrastruttura in questo percorso Containerization and Virtualization.