Formattazione YAML

Strumento che uniforma il rientro di un documento YAML e sa convertirlo in JSON. Rileva anche le tabulazioni intrufolate e le incoerenze nei rientri.

Che cos'è uno strumento di formattazione YAML

Uno strumento di formattazione YAML prende un documento con rientri irregolari e lo riscrive con un rientro uniforme di due o quattro spazi, controllando al tempo stesso la sintassi. I file di configurazione tendono ad accumulare rientri disomogenei dopo ripetuti copia e incolla e modifiche manuali, e spesso il primo segnale del problema arriva molto dopo, sotto forma di un errore criptico della pipeline di integrazione continua o dello strumento di gestione della configurazione. Poiché questo strumento funziona interamente nel browser, potete verificare file di configurazione delicati senza inviarne il contenuto a un server esterno.

Lo strumento si basa su un analizzatore leggero sviluppato appositamente, rivolto al sottoinsieme di uso comune di Docker Compose, GitHub Actions e dei manifesti di Kubernetes: mappature, elenchi, collezioni in linea e tipi scalari fondamentali. Non prevede funzioni avanzate come ancore (&), alias (*), documenti multipli o scalari a blocchi (|/>); se lavorate con uno YAML che dipende da queste caratteristiche, conviene affiancare questo strumento a un analizzatore completo.

Come si usa lo strumento di formattazione YAML

Incollate il vostro YAML Incollate lo YAML da formattare nel campo a sinistra. Se non avete un esempio a portata di mano, il pulsante «Esempio» ne inserisce uno con cui fare una prova.
Scegliete la modalità Selezionate «Formatta e convalida» per controllare la sintassi e uniformare il rientro, oppure «Converti in JSON» per ottenere il contenuto YAML in formato JSON.
Scegliete l'ampiezza del rientro Solo nella modalità «Formatta e convalida» potete scegliere fra due o quattro spazi per l'output, in base alla convenzione già seguita nel vostro progetto.
Verificate il risultato Se lo YAML è valido, a destra compare il risultato formattato (o la conversione in JSON). In caso contrario compaiono un messaggio d'errore e il numero di riga, così potete andare subito al punto del problema.
Copiate il risultato Il pulsante «Copia» mette il risultato negli appunti, pronto per essere reincollato nel vostro file di configurazione.

Consigli per sfruttarlo al meglio

Lo strumento si serve di un analizzatore leggero scritto appositamente e prevede coppie di chiave e valore, annidamenti, elenchi e le forme in linea [a, b, c] e {a: 1}.
Anche incollando uno YAML con rientri disomogenei, di tre o cinque spazi, se l'analisi riesce potrete riprodurlo uniformato a due o quattro spazi.
La modalità di conversione in JSON mostra un'anteprima del contenuto YAML tradotto in JSON: comoda per il confronto con le configurazioni dell'integrazione continua e con le risposte delle interfacce.
In caso d'errore compare il numero di riga: verificate il rientro di quella riga oppure la mancanza dello spazio dopo i due punti.
La specifica YAML vieta i rientri con tabulazioni: impostando il vostro programma di scrittura in modo che le converta in spazi eviterete inconvenienti.

Quando può servire questo strumento

Verifica delle configurazioni CI prima del commit

Passate i file .yml di GitHub Actions o GitLab CI attraverso questo strumento prima del commit, per scoprire rientri rovinati o tabulazioni intrufolate prima che la pipeline si interrompa per un errore di sintassi.

Riordino dei manifesti Kubernetes

I manifesti di Deployment e Service modificati da più persone finiscono spesso con rientri disomogenei: uniformateli alla convenzione della vostra squadra, per esempio due spazi, prima di inviarli in revisione.

Convalida dei file Docker Compose

Gli errori di rientro in docker-compose.yml passano spesso inosservati finché il contenitore non si avvia: controllare qui prima sintassi e coerenza del rientro dà maggiore tranquillità.

Confronto fra YAML e JSON

Quando la stessa configurazione o gli stessi dati di un'interfaccia servono sia in YAML sia in JSON, la modalità «Converti in JSON» mostra il risultato della conversione, da usare poi con altri strumenti basati su JSON o con la convalida di uno schema.

Glossario

YAML: Acronimo ricorsivo di «YAML Ain't Markup Language», un formato di serializzazione dei dati che esprime la struttura gerarchica per mezzo del rientro. È molto diffuso nei file di configurazione.
Rientro: Lo spazio bianco all'inizio di una riga, con cui YAML esprime le relazioni fra elemento genitore ed elemento figlio. Per specifica, il rientro non può mai usare tabulazioni.
Mappatura: Una struttura che rappresenta i dati come coppie «chiave: valore», equivalente a un array associativo o a un oggetto in altri linguaggi.
Elenco (sequenza): Una struttura che elenca valori in ordine, in cui ogni voce inizia con un trattino seguito da uno spazio («- »).
Forma in linea: Un modo di scrivere mappature ed elenchi su un'unica riga, come {a: 1} oppure [a, b, c], senza fare affidamento sul rientro.
Ancore e alias: Un meccanismo per cui un contenuto definito con &nome può essere riutilizzato altrove con *nome, evitando di ripetere gli stessi valori. Questo strumento non lo prevede.
Scalare a blocchi: Un modo di scrivere stringhe su più righe con | (che conserva gli a capo) o > (che li trasforma in spazi). Questo strumento non lo prevede.
Problema della Norvegia: Una nota insidia dello YAML per cui valori senza virgolette come no o yes vengono interpretati come valori logici anziché come semplici stringhe.

Domande frequenti

Per i file di configurazione che una persona modifica e revisiona a mano — configurazioni dell'integrazione continua, manifesti di Kubernetes — conviene YAML, che ammette i commenti ed è più leggibile. Per gli scambi fra programmi, come le risposte delle interfacce, è preferibile JSON, meno ambiguo e più rapido da analizzare.

La specifica vieta di usarle nel rientro e la maggior parte degli analizzatori interrompe l'elaborazione con un errore di sintassi. Conviene impostare il proprio programma di scrittura in modo che converta automaticamente le tabulazioni in spazi.

No. Si rivolge al sottoinsieme di uso comune — mappature, elenchi, forme in linea e tipi scalari fondamentali — che ricorre in Docker Compose, GitHub Actions e simili; funzioni avanzate come ancore, alias, documenti multipli e scalari a blocchi, con i segni | e >, non sono previste.

È la celebre insidia per cui, scrivendo senza virgolette no, yes, on oppure off, molte implementazioni li interpretano come valori logici e non come stringhe, per esempio il codice di quel paese. Per trattarli come testo occorre racchiuderli fra virgolette, scrivendo "no".

A proposito — perché YAML si è imposto nei file di configurazione

YAML, il cui nome ricorsivo dichiara scherzosamente che «non è un linguaggio di marcatura», è un formato di serializzazione dei dati comparso nel 2001. Non richiedendo marcatori di chiusura come l'XML e presentandosi in forma assai più snella, dagli anni Dieci si è largamente affermato come formato dei file di configurazione dell'infrastruttura: Docker Compose, GitHub Actions, i manifesti di Kubernetes.

La scelta di esprimere la struttura con il rientro, però, se da un lato agevola la lettura, dall'altro rende facile guastare tutto con un copia e incolla. Se poi tabulazioni e spazi si mescolano, molti analizzatori non segnalano alcun errore e interpretano la struttura in modo sbagliato: un terreno fertile per errori di configurazione involontari.

C'è poi la celebre insidia detta «problema della Norvegia»: scrivendo senza virgolette il codice di quel paese, no, molte implementazioni lo interpretano come il valore logico falso. Anche il fatto che le versioni 1.1 e 1.2 della specifica considerino valori logici stringhe diverse contribuisce ai problemi di compatibilità fra le implementazioni.

Vedi tutte le curiosità