Cos'è YAML? Basi, 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. 

Cos'è YAML?

YAML (Yet Another Markup Language / YAML Ain't Markup Language) è un formato di serializzazione dei dati che privilegia leggibilità e facilità d'uso. Mentre XML usa una combinazione di tag annidati simili a HTML e JSON usa parentesi graffe e virgolette, un po' come i dizionari di Python, YAML è più conciso e usa l'indentazione per definire la struttura, risultando più intuitivo per le persone.

YAML supporta vari tipi di dato, inclusi scalari (stringhe, numeri, booleani), sequenze (liste) e mapping (coppie chiave-valore). È ampiamente usato nei file di configurazione, nell'automazione dell'infrastruttura e nello 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 approfondire YAML anche sul suo sito web!

Sintassi e struttura di YAML

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

Regole di base della sintassi

Ci sono alcune semplici regole sintattiche per YAML: 

• Gli spazi di indentazione indicano la struttura, quindi evita le tabulazioni! 
• Le coppie chiave-valore seguono la struttura key: value, simile ad altri linguaggi. 
• Usare i trattini all'inizio delle righe denota una 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 denota informazioni fornite a diversi file di configurazione e impostazioni. Non è necessario 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 usando i trattini (-). Questo ti consente di elencare più oggetti sotto un'unica chiave. Spesso, quando lette da editor di markup, vengono visualizzate con punti elenco.

fruits:
  - Apple
  - Banana
  - Cherry

Dati annidati

Le strutture annidate consentono una rappresentazione gerarchica dei dati tramite 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 ripiegato). 

• Il blocco letterale | creerà una nuova riga \n per ogni a capo. 
• Il blocco ripiegato > creerà 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 ripiegato):

This is another multi-line string.

Tipi di dato in YAML

YAML supporta vari tipi di dato, 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 referenziarli successivamente con 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 <<: permette di unire coppie chiave-valore da un'anchor in 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 i valori manualmente sarebbe inefficiente. Aiutano a mantenere i file YAML DRY (Don't Repeat Yourself) e semplificano 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 rende semplice per chiunque prendere file di set-up YAML di 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 rispetto a JSON o XML.

Scopri di più su YAML e sul suo utilizzo in Docker in tquesto corso di Docker intermedio.

Serializzazione e trasferimento dei dati

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

Ad esempio, un body di richiesta API formattato in YAML:

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

La struttura basata sull'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 del 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 di Introduzione a Kubernetes.

Documentazione API

Specifiche API come OpenAPI e Swagger usano YAML per definire endpoint e strutture dati in modo facilmente leggibile. 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 API RESTful. Questo consente di fornire un chiaro blueprint per generare SDK client, documentazione API interattiva e test automatizzati. Questo formato strutturato assicura coerenza tra le 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 PyYAML di Python 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 comprensivo tutorial su JSON in Python.

Validare i file YAML

Per garantire una struttura corretta, puoi usare strumenti per controllare la presenza di tab al posto degli spazi o problemi anomali 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

Modificare 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 incappare in problemi e refusi lavorando 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!

Mescolare tab e spazi

YAML si basa sugli spazi per l'indentazione: non mescolare mai spazi e tab. Le tabulazioni semplicemente romperanno il tuo script YAML. È una scelta consapevole, perché i sistemi leggono le tab in modo diverso e, per minimizzare l'impatto, gli spazi sono l'opzione preferita.

Indentazione errata

Assicurati di mantenere un'indentazione coerente per evitare errori di parsing. Poiché le indentazioni sono l'unico metodo di YAML per indicare la gerarchia, un'analisi errata può causare problemi nel tuo codice. È facile finire per annidare una coppia key: value nel posto sbagliato, quindi fai attenzione alle 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 necessitano delle virgolette per essere letti come stringhe.

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

Usando una corretta validazione, una modifica strutturata 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 nella configurazione, nella serializzazione dei dati e nell'automazione dell'infrastruttura. Capendo 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 viene 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.