Convertire TOML in YAML

I fatti su un progetto vivono sempre più in un file TOML — il nome del pacchetto, le versioni Python o Rust supportate, i flag di funzionalità, l’insieme di dipendenze. Ciò che consuma quei fatti è, con la stessa coerenza, YAML: un workflow GitHub Actions, un file valori Helm, un insieme di variabili Ansible.

Quindi il lavoro di solito non è una migrazione ma una trascrizione: portare i valori in sintassi YAML accuratamente, poi spostare le parti che servono in un file con una propria forma. L’output non deve essere un workflow valido. Deve essere un rendering fedele da cui prelevare senza riscrivere un numero di versione.

TOML è insolito tra i formati di configurazione nell’avere veri tipi data e datetime, scritti senza virgolette: launch = 2026-03-01T08:00:00Z. Arrivano nel YAML allo stesso modo — senza virgolette attorno — ciò che YAML riserva per un timestamp. Convertite lo stesso manifest in JSON e ottenete gli stessi caratteri dentro una coppia di virgolette.

Cosa vi compra dipende interamente dal loader. Rileggete l’output con la stessa libreria che lo ha scritto, che segue lo schema core YAML 1.2, e ognuno di quei valori torna una stringa: 1.2 non ha risolutore di timestamp. Leggetelo con PyYAML o Psych di Ruby, ancora su YAML 1.1, e i primi due diventano datetime mentre at: 08:00:00.000 si risolve come il numero sessagesimale 28800.

Entrambi i target scrivono gli stessi caratteri per una data, quindi l’argomento riguarda dove vive il tipo. Nel YAML il valore non ha virgolette ed è abbastanza autodescrittivo che un loader 1.1 lo tipizzerà senza essere istruito. In XML la stessa data è testo di elemento, e cosa significa viene da uno schema che qualcun altro mantiene.

Questo taglia in entrambe le direzioni. Uno schema è un meccanismo di applicazione, e se il sistema ricevente ne ha uno, una data tipizzata male viene catturata alla porta invece che tre passi dentro una pipeline. Scegliete YAML quando la destinazione è un workflow che rileggerà il valore con il proprio loader e voi controllate quale loader sia; scegliete XML quando qualcosa a valle validerà il documento.

Un’intestazione [package] diventa una chiave di primo livello con i suoi valori indentati di due spazi sotto. Un’intestazione [tool.black] diventa tool: contenente black: contenente le impostazioni, perché un’intestazione di tabella puntata è annidamento piuttosto che un nome con punti.

L’ordine è l’ordine visto dal parser, il che per TOML significa che i valori sciolti in cima al file vengono prima e ogni tabella segue nell’ordine in cui è stata scritta. Ciò che si sposta è qualunque cosa espressa con chiavi puntate sparse nel file — quelle vengono raccolte sotto un unico genitore nel YAML.

Questo è il vero cambio di regime ed è facile da perdere perché l’output sembra così simile. In TOML, enabled = true è un booleano perché la sintassi lo dice, e version = "1.0" è una stringa perché tra virgolette. In YAML, uno scalare senza virgolette è ciò che il parser decide che sia.

Lo scrittore quota dove conta: una stringa di cifre esce quotata, quindi version = "1.0" resta version: "1.0" e non il numero 1. Ciò che non quota è NO, yes, on e off, perché sotto YAML 1.2 sono stringhe ordinarie. Caricatelo con PyYAML o Psych, ancora YAML 1.1, e diventano booleani.

Un blocco [[bin]] ripetuto è la forma lista-di-record di TOML, e si converte nella forma che tutti scrivono a mano in YAML: un trattino per voce, chiavi indentate sotto. Gli array semplici si comportano allo stesso modo, una riga con trattino per elemento.

Quella forma a blocco è ciò che la maggior parte degli strumenti YAML documenta, quindi le voci di solito si incollano in un workflow senza riformattazione. Se la destinazione vuole davvero stile flow, è una modifica manuale, e piccola.

Una stringa TOML tra triple virgolette che contiene uno script mantiene la sua struttura a righe. Lo scrittore la emette come scalare a blocco — la chiave, poi una pipe, poi le righe vere indentate sotto — piuttosto che come una riga con sequenze di escape.

I valori lunghi su una sola riga sono gestiti diversamente: una stringa senza a capo ma con molta lunghezza viene piegata su righe di continuazione attorno a ottanta colonne, e YAML rilegge quelle piegature come spazi, quindi il valore è invariato.

TOML e YAML supportano entrambi commenti con #, e un manifest ne è di solito pieno: perché una dipendenza è fissata a una release patch, quale di due impostazioni è deliberata. Nulla sopravvive, perché il lettore scarta i commenti in entrata e lo scrittore non ne ha da posizionare in uscita.

Per un frammento che state per incollare è irrilevante. Per qualunque cosa intendiate conservare, è la ragione per cui il TOML resta la fonte di verità e il YAML viene generato: due file con gli stessi valori e solo uno con il ragionamento è un problema di manutenzione in attesa di essere scoperto.

L’output usa un sottoinsieme semplice del linguaggio. Non ci sono ancore né alias — una sotto-tabella ripetuta appare due volte per intero piuttosto che una volta con un riferimento, perché i valori analizzati sono oggetti separati. Non c’è null da nessuna parte, perché TOML non ha null da convertire.

Se la destinazione si aspetta una di queste cose, le state aggiungendo a mano. Un insieme di variabili Ansible che si basa su tag vault, o un file valori Helm costruito attorno ad ancore, è un file in cui questa conversione confluisce piuttosto che uno che produce.

Il controllo più economico è un giro completo. Caricate l’output con qualunque cosa lo caricherà infine e confrontate una manciata di valori con il manifest — la versione, una data, qualunque cosa sembrasse un numero e dovrebbe essere una stringa.

yq eval . out.yaml riformatta e segnala un errore di sintassi se presente. Farlo una volta è più veloce che debuggare una pipeline che ha girato con version: 1 dove intendevate "1.0".

In questa scheda del browser, con JavaScript ordinario. Nulla viene caricato, non c’è motore da scaricare prima, non c’è account né limite giornaliero. Aprire il pannello di rete e convertire qualcosa è come confermarlo.

I manifest sono abbastanza piccoli che il tetto gratuito di 100 MB è teorico, ma non sono sempre pubblici. La lista dipendenze di un repository privato nomina pacchetti e registri interni, e un blocco [tool] a volte porta hostname o percorsi che dicono più su un’organizzazione di quanto chiunque intenda.