Convertire YAML in JSON

YAML è il formato con cui si scrivono a mano manifesti Kubernetes, pipeline CI, file di configurazione Docker Compose e impostazioni di decine di altri strumenti da riga di comando — è comodo da leggere e scrivere. JSON è quello che quasi ogni libreria, API o script si aspetta di ricevere in ingresso.

Chi arriva qui di solito ha già il file YAML pronto e deve darlo in pasto a qualcosa che parla solo JSON: un endpoint da testare, uno script Node che fa `JSON.parse`, un tool che valida schemi JSON Schema. Il resto di questa pagina riguarda che cosa sopravvive esattamente al passaggio.

Il file YAML viene interpretato in una struttura dati JavaScript ordinaria — oggetti, array, stringhe, numeri, booleani, valori nulli — e quella stessa struttura viene scritta come testo JSON con un’indentazione di due spazi, la stessa leggibilità che aveva l’originale.

Tutto avviene con JavaScript puro eseguito nella pagina: non c’è un motore da scaricare a parte, e la conversione parte nell’istante in cui il file viene rilasciato.

A differenza di CSV, TSV o INI, che possono contenere solo tabelle o coppie piatte, JSON descrive esattamente lo stesso tipo di albero che YAML descrive: oggetti dentro oggetti, liste dentro oggetti, senza limite di profondità. Non c’è quindi bisogno di appiattire nulla, ed è per questo che la coppia è classificata come senza perdita nella maggior parte dei casi.

Le eccezioni sono poche e specifiche — gli alias YAML e i tag personalizzati, descritti più sotto — e riguardano solo i file che li usano davvero. Un file YAML scritto con la sintassi comune, senza quelle due funzionalità avanzate, arriva in JSON esattamente com’era.

YAML permette commenti che iniziano con `#`, spesso usati per spiegare perché un valore è impostato in un certo modo. Il parser li scarta già durante la lettura: nella struttura dati che arriva alla fase di scrittura non c’è nessun posto dove un commento potrebbe stare.

JSON, del resto, non ha una sintassi per i commenti, quindi anche se venissero letti non ci sarebbe modo di scriverli nel risultato. Chi ha un file YAML pesantemente commentato dovrebbe copiare quelle annotazioni altrove prima di convertire, se servono ancora dopo.

Le chiavi di un oggetto non vengono riordinate alfabeticamente né in nessun altro modo: la struttura dati mantiene l’ordine in cui il parser le ha incontrate leggendo il file, e la scrittura del JSON le emette in quello stesso ordine.

Per un file di configurazione dove l’ordine delle sezioni ha un valore anche solo documentale — prima le variabili globali, poi i servizi, poi le regole — questo significa che il JSON risultante si legge nello stesso ordine logico dell’YAML da cui viene.

YAML permette di definire un valore una volta con un ancora (`&nome`) e riusarlo altrove con un riferimento (`*nome`), evitando di ripetere lo stesso blocco più volte nel file. Il parser risolve questi riferimenti espandendoli per intero nel punto in cui compaiono.

Il risultato è che il JSON contiene il valore ripetuto per esteso ovunque veniva referenziato, non un collegamento fra le due occorrenze — cosa che JSON, del resto, non saprebbe rappresentare comunque. Su un file che usa gli alias per evitare ripetizioni lunghe, questo può far crescere sensibilmente le dimensioni del risultato rispetto all’originale.

YAML permette di annotare un valore con un tag personalizzato, come `!Ref` o `!!python/object`, usato da certi strumenti per dare un significato speciale a quel valore oltre al suo tipo di base. Questi tag non vengono portati nel JSON: solo il valore sottostante sopravvive, senza l’annotazione che gli dava un significato diverso.

Per la configurazione più comune — Kubernetes, Docker Compose, GitHub Actions — questo non è mai un problema, perché nessuno di questi formati usa tag personalizzati. Vale la pena controllarlo solo con file YAML scritti per strumenti specifici che dichiaratamente li usano, come certi template CloudFormation.

Un valore scritto in YAML nella forma di una data o di una data-ora — `2024-03-15` o `2024-03-15T10:30:00Z` — viene riconosciuto come tale dal parser e arriva nel JSON come una stringa in formato ISO 8601, lo stesso formato standard che quasi ogni libreria che legge JSON si aspetta.

Non arriva come un numero né in un formato specifico della macchina che ha fatto la conversione: il formato è lo stesso indipendentemente da dove gira il convertitore, il che rende il risultato prevedibile per chi lo consuma a valle.

La lettura e la scrittura avvengono interamente nella scheda del browser: il contenuto del file YAML non lascia mai il dispositivo, e lo si può verificare aprendo la scheda di rete degli strumenti per sviluppatori mentre la conversione avviene.

Ogni file può arrivare fino a 100 MB, e se ne possono convertire fino a cento in una sola volta, restituiti come un archivio ZIP con un JSON per ciascun file YAML originale — comodo per chi ha un’intera cartella di manifesti da migrare in un colpo solo.