Formattatore YAML: formatta, re-indenta e valida YAML

YAML è sensibile agli spazi bianchi, quindi un tab capitato per sbaglio o un'indentazione incoerente non è solo brutta da vedere —— cambia il significato o rompe il parsing. Un formatter YAML risolve questo: ri-indenta il tuo YAML a una profondità coerente, normalizza la spaziatura, e (opzionalmente) ordina le key, in modo che il file sia leggibile e produca diff puliti. Questa guida spiega cosa fa un formatter YAML, le regole di indentazione che impone, le trappole di tipo da tenere d'occhio, e quando formattare YAML rispetto a convertirlo in JSON.

Cosa fa un formatter YAML

Un formatter parsa il tuo YAML in una struttura dati e lo riserializza con uno stile coerente. I dati non cambiano —— solo la presentazione viene normalizzata:

• Ri-indenta ogni livello a una larghezza fissa (di solito 2 spazi) e sostituisce i tab con spazi
• Normalizza la spaziatura intorno ai due punti, ai trattini di lista e alle collection inline
• Opzionalmente ordina le key per un ordine canonico amico dei diff
• Convalida come effetto collaterale —— se non riesce a parsare, hai un errore di sintassi da risolvere prima

# Prima —— indentazione mista, difficile da scorrere
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# Dopo —— indent a 2 spazi, normalizzato
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

Perché formattare YAML

• Leggibilità —— pipeline CI, manifest Kubernetes e file Docker Compose si annidano in profondità; un'indentazione coerente li rende scorrevoli.
• Diff e review puliti —— una formattazione normalizzata (e key ordinate) significa che una pull request mostra solo modifiche reali, non rumore di whitespace.
• Beccare gli errori in anticipo —— la formattazione riesce solo su YAML valido, quindi un formatter funge anche da check rapido di validità.
• Coerenza nel team —— un solo stile applicato automaticamente, invece di abitudini d'indentazione per autore.

Le regole di indentazione che un formatter impone

La maggior parte degli errori YAML sono errori di indentazione, ed è esattamente ciò che un formatter standardizza:

• Solo spazi —— mai tab. YAML proibisce i caratteri tab per l'indentazione. Un singolo tab è il bug YAML più comune del «perché non parsa?».
• Profondità coerente. Key fratelli devono essere indentati dello stesso numero di spazi rispetto al genitore. Un formatter riscrive tutto a una larghezza fissa.
• Allineamento delle liste. Gli item in una block sequence (-) si allineano sotto la loro key; un formatter normalizza se il trattino è indentato o a filo.

Trappole di tipo quando riformatti

La formattazione preserva i dati, ma l'inferenza di tipo di YAML può comunque sorprenderti quando i valori sono senza virgolette —— vale la pena saperlo prima di fidarsi dell'output:

• Il «Norway problem». Senza virgolette, NO, yes, on, off possono essere letti come booleani, così il codice paese NO diventa false. Metti tra virgolette questi valori per tenerli stringhe.
• Zeri iniziali e numeri grandi.007 può perdere gli zeri se letto come numero; interi molto grandi possono perdere precisione. Metti tra virgolette gli ID che devono restare stringhe.
• Date e timestamp. Alcuni parser convertono stringhe senza virgolette simili a date in tipi timestamp. Mettile tra virgolette se ti serve la stringa letterale.

Stile block vs stile flow

YAML ha due modi di scrivere le collection: block (indentato, orientato alle righe) e flow (inline, stile JSON con [] / {}):

# block
ports:
  - 80
  - 443

# flow (stessi dati)
ports: [80, 443]

I formatter tipicamente normalizzano allo stile block per leggibilità. Lo stile flow è compatibile con JSON —— utile quando si embedda YAML dentro tooling solo-JSON —— ma più difficile da scorrere all'aumentare dell'annidamento.

Anchor e alias: snippet riutilizzabili

& segna un anchor; * lo referenzia. Utile per condividere config tra servizi senza copia-incolla, e i formatter li preservano:

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

Nota: anchor e alias spariscono quando converti in JSON —— JSON non ha tipo riferimento, quindi i valori vengono messi inline. Un round-trip YAML → JSON → YAML li perde.

Lint oltre il parsing: yamllint

Un formatter normalizza la forma; yamllint impone una guida di stile (lunghezza riga, ordine key, marker di inizio documento, valori truthy, spaziatura commenti). Combinali in CI: prima formatta, poi linta con le regole che sceglie il tuo team.

Formattare YAML vs convertire in JSON

Formattare tiene il file come YAML —— meglio quando gli umani continueranno a modificarlo. Convertire in JSON è quando un programma lo deve consumare (la maggior parte delle app parsa solo JSON a runtime). Visto che YAML 1.2 è un superset stretto di JSON, la conversione è senza perdita per i dati; vedi Convertire YAML in JSON e JSON vs YAML per sapere quando usarli.

Formatta e valida YAML nel browser

Incolla il tuo YAML in il validatore e formatter YAML di fixjson e clicca Format YAML per ri-indentarlo e normalizzarlo, oppure To JSON per convertirlo. Riporta la riga esatta di qualsiasi errore di sintassi, e tutto gira nel tuo browser —— niente upload —— il che conta per file di configurazione che contengono host, segreti o impostazioni interne.

Domande frequenti

Cosa fa un formatter YAML?

Parsa il tuo YAML e lo riserializza con indentazione e spaziatura coerenti (e opzionalmente key ordinate), così il file è leggibile e amico dei diff. I dati non cambiano —— viene normalizzata solo la formattazione.

Perché il mio YAML non parsa?

Quasi sempre indentazione: un carattere tab (YAML proibisce i tab per l'indentazione) o key fratelli a profondità incoerenti. Un formatter riscrive tutto a una larghezza singola basata sugli spazi, il che fa emergere e risolve la maggior parte di questi casi.

Formattare YAML cambia i miei dati?

No —— cambia solo whitespace e ordine delle key. Attento però ai valori senza virgolette: YAML può inferire i tipi (il «Norway problem»), quindi metti tra virgolette valori come NO o 007 che devono restare stringhe.

Devo formattare YAML o convertirlo in JSON?

Formatta quando gli umani continuano a modificare il file; converti in JSON quando un programma lo consuma. Molti team scrivono YAML e convertono in JSON al caricamento.

Strumenti & guide correlati

• Validatore & Formatter YAML —— formatta, valida e converti YAML nel tuo browser
• Convertire YAML in JSON —— la conversione e le trappole d'indentazione
• JSON vs YAML —— differenze e quando usare l'uno o l'altro
• Come formattare JSON —— l'equivalente in JSON