Tutorial Sintassi YAML: Un'Introduzione Pratica

YAML (YAML Ain't Markup Language) è un formato di serializzazione dati leggibile dall'uomo ampiamente utilizzato in file di configurazione, pipeline CI/CD e infrastructure-as-code. Se lavori con Docker Compose, Kubernetes, GitHub Actions o Ansible, stai già usando YAML quotidianamente. Questo tutorial copre tutto ciò che ti serve per scrivere YAML con sicurezza.

Perché YAML?

Il vantaggio principale di YAML è la leggibilità. Confronta gli stessi dati in JSON e YAML:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML ottiene la stessa struttura con meno punteggiatura. Niente parentesi graffe, niente parentesi quadre per i casi semplici, nessuna quotatura obbligatoria. Questo rende i file di configurazione più facili da leggere e modificare a mano.

Tipi di Dati di Base

Scalari

YAML inferisce automaticamente i tipi dai valori:

string: hello world          # Stringa (nessuna quota necessaria)
quoted: "hello world"        # Stringa esplicita
integer: 42                  # Intero
float: 3.14                  # Float
boolean: true                # Booleano (true/false, yes/no, on/off)
null_value: null             # Null (anche ~ o vuoto)
date: 2025-01-15             # Data (ISO 8601)

Insidia comune: Valori come yes, no, on, off sono interpretati come booleani. Se intendi la stringa "yes", quotala: "yes".

Stringhe e Quotatura

Le stringhe raramente necessitano di quotatura, ma alcuni casi la richiedono:

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

Stringhe Multilinea

YAML ha due stili multilinea:

Blocco letterale (|) — preserva le interruzioni di riga:

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

Blocco ripiegato (>) — unisce le righe con spazi:

description: >
  This is a long paragraph
  that will be folded into
  a single line.

Aggiungi - per rimuovere i newline finali (|-, >-) o + per mantenerli (|+, >+).

Collezioni

Liste (Sequenze)

# Block style
fruits:
  - apple
  - banana
  - cherry

# Flow style (inline)
fruits: [apple, banana, cherry]

Mappe (Mapping)

# Block style
person:
  name: Alice
  age: 30
  city: London

# Flow style
person: {name: Alice, age: 30, city: London}

Strutture Annidate

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

Anchor e Alias

Gli anchor (&) e alias (*) permettono di riutilizzare i valori:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Sovrascrive il valore predefinito

La merge key << incorpora tutte le proprietà dall'anchor. Le proprietà definite dopo il merge sovrascrivono i valori ancorati. Leggi di più sui pattern avanzati degli anchor nella nostra guida ad anchor e alias YAML.

Documenti Multipli

Un singolo file YAML può contenere più documenti separati da ---:

---
# Documento 1: Config
apiVersion: v1
kind: ConfigMap
---
# Documento 2: Service
apiVersion: v1
kind: Service

Questo è comunemente usato nei manifest Kubernetes.

Insidie Comuni

1. Errori di Indentazione

YAML usa spazi, mai tab. L'indentazione incoerente è l'errore più comune:

# SBAGLIATO - indentazione mista
server:
  host: localhost
    port: 8080  # Errore: indentazione inattesa

# CORRETTO
server:
  host: localhost
  port: 8080

Usa il nostro Formattatore YAML per correggere automaticamente i problemi di indentazione.

2. Il Problema della Norvegia

I codici paese come NO (Norvegia) sono interpretati come booleano false:

# SBAGLIATO
countries:
  - NO  # Interpretato come false!
  - SE
  - DK

# CORRETTO
countries:
  - "NO"
  - SE
  - DK

3. Caratteri Speciali Non Quotati

Due punti, hash e parentesi nei valori necessitano di quotatura:

# SBAGLIATO
message: Error: file not found
url: http://example.com  # Potrebbe rompersi

# CORRETTO
message: "Error: file not found"
url: "http://example.com"

4. Insidia dei Numeri di Versione

I numeri di versione come 1.0 sono analizzati come float:

# SBAGLIATO
version: 1.0  # Diventa 1 (float)

# CORRETTO
version: "1.0"  # Stringa

Validazione del YAML

Valida sempre il tuo YAML prima del deploy. Gli errori di sintassi in YAML possono causare fallimenti criptici nelle applicazioni. Il nostro Validatore YAML controlla la sintassi istantaneamente, evidenziando la riga e la colonna esatta di qualsiasi errore.

Per un approfondimento sulle differenze tra YAML e JSON, vedi il nostro confronto YAML vs JSON.

FAQ

Quanti spazi devo usare per l'indentazione YAML?

Due spazi è la convenzione più comune, usata da Kubernetes, Docker Compose, GitHub Actions e la maggior parte degli strumenti DevOps. Alcuni progetti usano quattro spazi. La regola chiave è la coerenza all'interno di un file — non mescolare mai i livelli di indentazione.

YAML può includere commenti?

Sì, YAML supporta commenti su singola riga con #. Non esiste una sintassi per commenti multi-riga. I commenti vengono rimossi durante il parsing e non sono disponibili nella struttura dati caricata.

Risorse Correlate

• Formattatore YAML — Formatta e abbellisci file YAML
• YAML vs JSON — Quando usare quale formato
• YAML per Docker Compose — Pattern YAML specifici per Docker