Convertire JSON in YAML

Questa è l’unica conversione di questo gruppo di pagine in cui la risposta a «quanto mi costa» è davvero nulla. YAML 1.2, pubblicato nel 2009 e la versione che la specifica porta da allora, definisce JSON come un sottoinsieme : ogni documento JSON valido è già un YAML valido. La conversione riserializza lo stesso albero in uno stile diverso.

Questo rende il resto della pagina insolito. Non c’è un passo lossy di cui avvertire, nessun appiattimento, nessun tipo da approssimare. Quello che c’è invece è un insieme di domande su come il risultato sarà letto, e queste si rivelano contare più di qualsiasi perdita di dati farebbe.

Lo scrittore segue YAML 1.2, sotto il quale no, yes, on e off sono stringhe ordinarie. Quindi un valore JSON "no" viene scritto come un no nudo, senza virgolette, e rileggere quel documento con un parser 1.2 restituisce la stringa da cui si era partiti. È il comportamento corretto e fa un round-trip perfetto.

YAML 1.1 non è d’accordo. Risolve quelle stesse parole a booleani, e PyYAML — che è ciò che usa Ansible, gran parte del tooling Python e innumerevoli script interni — è un lettore 1.1. Così un codice paese di due lettere, un campo di risposta, una colonna chiamata consent : il valore entra come la stringa no ed esce come false. Se uno strumento Python è a valle, si virgolettino quei valori a mano dopo la conversione. È una piccola modifica ed è il modo più probabile in cui questa conversione produca un file formalmente corretto che si comporta nel modo sbagliato.

Le virgolette sono decise per valore, e solo dove la forma nuda verrebbe letta come qualcos’altro. La stringa "1.0" è virgolettata, perché senza virgolette è un numero. La stringa "null" è virgolettata, perché senza virgolette è il valore null. Una stringa che inizia con un cancelletto è virgolettata, perché un cancelletto nudo inizia un commento, e una stringa con spazi iniziali o finali è virgolettata, perché YAML altrimenti li eliminerebbe.

La regola è coerente ed è una regola 1.2, che è esattamente il punto della sezione precedente. Tutto ciò che lo scrittore virgoletta cambierebbe significato sotto YAML 1.2 ; le parole che lascia nude sono quelle che cambiano significato solo sotto 1.1. Una stringa a forma di data come 2024-01-01 è lasciata nuda per la stessa ragione, e un lettore 1.1 la trasforma in un timestamp.

Una stringa JSON non può contenere un a capo letterale, quindi uno script di shell, un certificato o un’istruzione SQL incorporati in un manifest JSON sono un’unica riga enorme con backslash-n al posto delle interruzioni. Rivedere una sua modifica non è davvero possibile.

Lo scrittore YAML emette quei valori come scalar a blocco : un carattere pipe, poi il testo su righe indentate proprie con le interruzioni di riga al loro posto. Uno script entrypoint di dodici righe diventa dodici righe nel file. Per chi converte perché il manifest deve essere rivisto da una persona, questo è di solito il singolo miglioramento più grande dell’output, ed è invisibile finché il file non ne contiene uno.

Un array JSON di oggetti si converte nella lista con prefisso dash che ogni esempio di Kubernetes e GitHub Actions è scritto in : un trattino, poi la prima chiave sulla stessa riga e il resto indentato sotto. Containers, steps, volumes, jobs — tutti arrivano nella forma che la documentazione mostra.

Questo conta per la revisione più che per la correttezza, e la revisione è il motivo per cui il file esiste. Un revisore che scorre una lista di sei passi di deployment in YAML può vedere i confini tra di essi senza contare le parentesi, che è il motivo per cui l’ecosistema ha scelto il formato nonostante le sue trappole di indentazione.

JSON non porta commenti, il che segue dalla grammatica in RFC 8259 più che essere un caso dei parser — non c’è produzione per uno, quindi un parser conforme non ha nulla da accettare. YAML li porta ovunque una riga possa iniziare con un cancelletto. Convertire un manifest generato in YAML è molto spesso non una questione di sintassi — è fare del file un posto dove la ragione di un valore possa vivere accanto al valore.

Nell’output non ci sono commenti, perché l’input non ne aveva da dare. Aggiungerli è la prima modifica che vale la pena fare, e i più utili non sono mai descrizioni di cosa sia un campo. Si scriva perché il conteggio delle repliche è tre, a quale altro repository il tag dell’immagine deve corrispondere, e cosa si rompe se il timeout viene abbassato.

YAML ha ancore e alias, che permettono di definire un blocco una volta e riferirlo in tre posti, e ha più documenti in un file separati da tre trattini. Entrambi sono ampiamente usati — i file compose e i bundle Kubernetes vi fanno affidamento — e nessuno dei due può uscire da una sorgente JSON, perché JSON non ha modo di esprimere l’uno o l’altro.

Così il file convertito è corretto e piatto : tutto ciò che è ripetuto nel JSON è ripetuto nello YAML. Estrarre la ripetizione con un’ancora è una modifica manuale, e vale la pena farla solo dove la ripetizione è genuina. Un bundle di manifest separati concatenati in un array JSON è l’altro caso, e lì ciò che serve sono più documenti in un file, che è di nuovo una modifica più che una conversione.

Lo scrittore preserva l’ordine in cui le chiavi sono arrivate, quindi apiVersion, kind e metadata restano dove erano invece di essere ordinati. Né JSON né YAML definiscono l’ordine delle mappe come significativo, e molti strumenti riordinano liberamente, ma un manifest le cui chiavi sono state alfabetizzate è più difficile da leggere e produce un diff ampio senza motivo.

Questo vale la pena saperlo quando si confronta l’output con un file già nel repository. Se i due differiscono solo nell’ordinamento, la differenza viene da qualunque cosa abbia prodotto il JSON, non da questa conversione — rileggere una risorsa da un cluster, per esempio, restituisce i campi nell’ordine del server API invece che nell’ordine in cui li avete scritti.

Il controllo che costa meno è il dry run dello strumento stesso : kubectl apply con --dry-run=client, docker compose config, o il linter di workflow per un file Actions. Ognuno parsa il documento e riporta la forma che ha trovato, il che coglie una chiave fuori posto molto più velocemente che leggere il file.

Il controllo che coglie il problema delle virgolette è diverso e va fatto di proposito : si cerchino nel file convertito le occorrenze nude di yes, no, on, off e ogni data senza virgolette, e si decida per ognuna se un lettore YAML 1.1 la vedrà mai. Richiede un minuto ed è l’unica parte di questa conversione che un parser non segnalerà.

La conversione gira in questa scheda. Il JSON è parsato dal parser stesso del browser e lo YAML è scritto da una libreria caricata su richiesta, quindi nessuna richiesta porta il documento da qualche parte, non c’è iscrizione e non c’è limite giornaliero, e il livello gratuito accetta fino a 100 MB — ben più di qualsiasi manifest.

Per chi legge è una preoccupazione pratica più che astratta. Un manifest estratto da un cluster in esecuzione contiene nomi host interni, percorsi di registro, nomi di service account e la forma dell’infrastruttura, e un discreto numero di organizzazioni tratta l’incollare quello in un convertitore web pubblico come un incidente. Qui non c’è nulla da incollare e nulla da inviare.