YAML in JSON: Converti manifest, Componi file e pipeline senza perdere dati

Ho passato un pomeriggio l'anno scorso a eseguire il debug di un file di valori Helm che un collega aveva giurato fosse corretto Ogni chiave sembrava giusta Il servizio si è rifiutato di iniziare Il colpevole si è rivelato essere quattro caratteri: NO come codice paese, non citato, in un elenco di regioni Il parser YAML lo leggeva come booleano false, il modello reso false in un'intestazione, e la richiesta è stata respinta a valle con un messaggio di errore che non menzionava né YAML né Norvegia Quel bug è abbastanza famoso per avere un nome - il problema Norvegia - ed è solo uno di una famiglia di sorprese in attesa in un formato che la maggior parte di noi tratta come & quot; JSON con spazi bianchi più belli.& quot;

tl; dr: la Convertitore Yaml a JSON analizza un documento YAML e stampa l'equivalente JSON, risolvendo ancore, alias, chiavi di unione e scalari di blocco lungo il percorso. Vedere la configurazione come JSON ti mostra esattamente cosa significa il parser che ha deciso i tuoi valori - quali tipi ha dedotto, quali riferimenti ha ampliato - prima che tale interpretazione raggiunga un cluster. Funziona interamente nel tuo browser.

Convertire YAML in JSON non è solo un cambio di formato È l'audit più veloce disponibile di ciò che la tua configurazione contiene effettivamente JSON non ha commenti, né ancoraggi, né digitazione implicita oltre a ciò che la sintassi afferma a titolo definitivo, quindi la visualizzazione JSON di un manifest è la versione risolta e inequivocabile di esso Questa guida copre il modo in cui YAML mappa su JSON, il tipo e i comportamenti di riferimento che causano incidenti reali e come utilizzare il convertitore quando si esegue il debug di una configurazione, scripting rispetto a un manifest o scrittura di un dispositivo di prova.

Cosa fa effettivamente la conversione di YAML in JSON?

La relazione è definita, non incidentale: il Specifica YAML 1.2 afferma che YAML è un superset di JSON, quindi ogni documento JSON è già valido YAML YAML e JSON descrivono le stesse tre cose: mappature di chiavi di valori, sequenze ordinate e scalari Conversione cammina sul documento YAML ed emette ogni costrutto nel suo equivalente JSON Una mappatura di blocchi diventa un oggetto Una sequenza di blocchi diventa un array Uno scalare diventa una stringa, un numero, un booleano o un nullo, a seconda di come lo schema core YAML lo risolve.

La parte strutturale è poco interessante perché è meccanica La parte interessante è tutto ciò che YAML può esprimere che JSON non può, perché è lì che il convertitore deve prendere una decisione per tuo conto:

Funzione YAML	Cosa ottiene JSON	Perché è importante
Commenti (# ...)	Caduto	JSON non ha sintassi dei commenti; la documentazione nella tua configurazione non sopravvive
Ancoraggi e alias (&base, *base)	Copie ampliate	JSON non ha sintassi di riferimento, quindi i blocchi condivisi vengono duplicati
Unisci le chiavi (<<: *base)	Appiattito nell'oggetto	Le chiavi esplicite sovrascrivono quelle unite, secondo le specifiche della chiave di unione
Blocca gli scalari (`	, &gt;`)	Una singola stringa con fughe
Documenti multipli (---)	Una serie di documenti	Un bundle Kubernetes diventa un array JSON, un elemento per risorsa
Tipizzazione implicita	Tipi risolti	Non citato 8080 diventa un numero, true un booleano, null un nullo

Quell'ultima riga è quella che vale la pena fissare JSON forza ogni valore a dichiarare il proprio tipo attraverso la sintassi: virgolette stringa media, cifre nude numero medio YAML deduce il tipo dalla forma del testo Convertire in JSON rende visibile l'inferenza Se ti aspettavi una stringa di versione e JSON ti mostra 1.1 dove diceva lo YAML 1.10, hai trovato un bug che altrimenti avresti spedito.

Perché la digitazione implicita di YAML's causa interruzioni reali

Lo schema core YAML 1.2 risolve uno scalare non quotato per pattern Le cifre diventano numeri interi Le cifre con punto decimale o esponente diventano float. true e false diventate booleani. null e ~ diventa nullo Tutto il resto è una stringa.

Sembra ordinato finché non soddisfi i valori che assomigliano a un tipo e sono intesi come un altro:

• Porti e ID. port: 08080 non è il numero 8080. uno zero iniziale lo rende un numero intero non valido sotto lo schema principale, quindi la maggior parte dei parser restituisce la stringa e alcuni più vecchi la interpretano come ottale. I codici postali, i numeri di telefono e gli ID account con zeri iniziali hanno lo stesso problema.
• Versioni. version: 1.10 è il galleggiante 1.1. Lo zero finale è andato e nessun parser ti avverte Confrontalo con un tag contenitore e la ricerca fallisce.
• Codici paese e lingua. Sotto YAML 1.1 - che PyYAML segue ancora per impostazione predefinita, insieme a molti strumenti Ruby e Java meno recenti - y, n, yes, no, on, e off sono booleani. NO, ON, e NA sono codici perfettamente ordinari di due lettere nel mondo reale.
• Tempi e sessagesimali. YAML 1.1 analizza anche 12:30 come numero in base 60, che è 750. stringhe simili a Cron o durate possono svanire in numeri interi.

Ognuno di questi è una corruzione silenziosa dei dati, non un errore di analisi Il documento è valido, la pipeline è verde e il valore è sbagliato Il convertitore' s Tieni le stringhe esiste un'opzione esattamente per questa classe di indagine: accendila e ogni semplice scalare ritorna come una stringa, così puoi confrontare le due conversioni fianco a fianco e vedere con precisione quali valori il parser stava reinterpretando Qualunque cosa il JSON mostri senza quell'opzione è ciò che il tuo parser di produzione sta facendo molto probabilmente oggi.

La correzione nella tua fonte YAML è sempre la stessa: cita qualsiasi cosa il cui significato sia testuale. port: "8080", version: "1.10", region: "NO". Le quotazioni non costano nulla e rimuovono l'intera categoria di bug Se si genera YAML da JSON anziché scriverlo, il Convertitore JSON a YAML applica tale quotazione automaticamente per valori ambigui.

Come si convertono ancore, alias e chiavi di unione

Gli ancoraggi sono YAML's risposta alla ripetizione Segni un nodo con &name, quindi fa riferimento più avanti con *name:

defaults: &defaults
  restartPolicy: Always
  terminationGracePeriodSeconds: 30

web:
  <<: *defaults
  replicas: 3

worker:
  <<: *defaults
  terminationGracePeriodSeconds: 120

JSON non ha modo di dire & quot; lo stesso valore di laggiù.& quot; Quindi il convertitore espande ogni riferimento in una copia completa L'output sopra diventa tre oggetti, ognuno dei quali porta il suo restartPolicy, e il JSON è più lungo dello YAML che lo ha prodotto Non è un difetto nella conversione - è ciò che significa YAML, scritto.

La chiave di unione << merita una nota propria perché la sua regola di precedenza è facile da ottenere all'indietro Le chiavi scritte esplicitamente nella mappatura del bambino vincono sulle chiavi tirate dall'unione Nell'esempio, worker finisce con un periodo di grazia di 120, non 30, indipendentemente dal fatto che la linea di unione appaia sopra o sotto la chiave esplicita Il convertitore implementa quella regola, quindi il JSON ti mostra la configurazione effettiva, post-unione - che di solito è la cosa che volevi effettivamente ispezionare.

Ne conseguono due usi pratici In primo luogo, quando una configurazione utilizza un ancoraggio pesante, la conversione in JSON è il modo più rapido per rispondere a & quot; a cosa si risolve effettivamente questo ambiente?" senza eseguire la distribuzione In secondo luogo, se un alias non ha un ancoraggio corrispondente - un risultato comune della suddivisione di un file grande in più - il convertitore lo segnala come un errore con il numero di riga, anziché produrre silenziosamente un null.

Come si convertono gli scalari a blocchi

YAML ha due modi per incorporare testo multi-riga e si comportano diversamente:

• Letterale (|) mantiene ogni interruzione di riga esattamente come scritta Utilizzala per script di shell, certificati PEM, SQL e qualsiasi cosa sensibile agli spazi bianchi.
• Piegato (>) unisce righe consecutive con un singolo spazio e tratta una riga vuota come un'interruzione di paragrafo Usala per la prosa che desideri racchiusa nel file sorgente ma unita nel valore.

Entrambi accettano un indicatore di chomping che controlla le newline finali Il default, chiamato clipping, mantiene esattamente una newline finale Un meno (A minus)|-) spoglia tutte le nuove linee finali. Un vantaggio (|+) li conserva ciascuno.

In JSON, tutto questo collassa in un'unica stringa con \n fughe Questo è un altro motivo per cui la vista JSON è utile: non è ambigua. UN | blocco la cui ultima riga è stata accidentalmente rientrata, oppure a > bloccare che piegare-unito due linee che si intendeva tenere separati, è ovvio in JSON e quasi invisibile in YAML Il convertitore gestisce anche il caso che cattura ingenue implementazioni - un # il carattere all'interno di un blocco letterale è contenuto, non un commento, il che conta nel momento in cui incorpori uno script di shell che inizia con uno shebang.

Come utilizzare il convertitore da YAML a JSON

Passaggio 1: incolla il documento

Incolla qualsiasi YAML nel pannello di input: un manifesto di Kubernetes, un docker-compose.yml, un flusso di lavoro GitHub Actions, un playbook Ansible, un .gitlab-ci.yml, o una configurazione dell'applicazione File multi-documento con --- i separatori vanno bene - ogni documento viene analizzato in modo indipendente Clicca Carica campione per partire da un Deployment realistico che esercita mappe annidate, sequenze, una raccolta vuota e uno scalare a blocchi letterali.

L'unica cosa che non analizzerà è il rientro con i caratteri di scheda YAML proibisce le schede a titolo definitivo e il convertitore lo dice con il numero di riga incriminato anziché indovinare Gli editor che inseriscono una scheda su Invio sono la solita fonte; la maggior parte ha un rientro & quot; converte in spazi& quot; comando che fissa l'intero file contemporaneamente.

Passo 2: Scegliere la forma di output

Scegli 2 spazi, 4 spazi, o Minificato. Minified è ciò che vuoi quando stai per incollare il risultato in un curl corpo o una variabile d'ambiente L'output rientrato è ciò che si desidera quando un essere umano deve leggerlo.

Ordina tasti riscrive le chiavi dell'oggetto in ordine alfabetico ad ogni livello Questo è prezioso quando si confrontano due versioni di una configurazione: due file che differiscono solo nell'ordine delle chiavi producono JSON ordinato identico, quindi un diff mostra solo cambiamenti reali. Alimenta entrambi gli output nel file JSON DIFF strumento e si ottiene un confronto strutturale preciso invece di uno linea per linea.

Tieni le stringhe disabilita la coercizione scalare, come descritto sopra Usalo quando vuoi vedere il testo grezzo di ogni valore, o quando un consumatore a valle tratta comunque tutto come una stringa.

Passo 3: Convertire e leggere gli errori

schioccare convertire. Se il documento è ben formato, il JSON viene visualizzato di seguito insieme al conteggio delle righe, al conteggio delle chiavi, alla dimensione dei byte e, per i flussi multidocumento, al numero di documenti trovati.

Se non è ben formato, l'errore nomina la riga I messaggi coprono i guasti che effettivamente accadono nella pratica: schede utilizzate per il rientro, una riga rientrata in modo incoerente con i suoi fratelli, una stringa quotata non terminata, un alias senza ancoraggio, una chiave di unione che punta a qualcosa che non è una mappatura Un numero di riga trasforma una caccia di cinque minuti in una correzione di cinque secondi.

Passaggio 4: copia, scarica o continua

Copia il JSON negli appunti o scaricalo come a .json file. Da lì, i passaggi successivi comuni sono la stampa e la convalida con il file Formattatore JSON, tipi di generazione per un caricatore di configurazione con JSON a dattiloscritto, ovvero derivando un contratto per la validazione CI con il Generatore di schemi JSON.

Flussi di lavoro reali adatti a questo

Effettuare il debug di un manifesto che & quot; sembra fine& quot;

Quando una distribuzione si comporta in modo inaspettato e lo YAML legge correttamente, convertilo Nove volte su dieci il JSON mostra immediatamente il problema: un valore che è diventato booleano, una chiave annidata di un livello meno profonda del previsto a causa di uno spazio vagante, un'ancora che si è espansa fino a diventare qualcosa di stantio La vista JSON rimuove l'ambiguità degli spazi bianchi che ha reso il bug invisibile.

Scripting contro configurazione

Gli script Shell e Node gestiscono JSON in modo nativo; YAML ha bisogno di una dipendenza Quando ho bisogno di estrarre ogni tag immagine da un pacchetto di manifest, convertendo prima in JSON e eseguendo il piping jq è più veloce che aggiungere una libreria YAML a uno script usa e getta Il convertitore's supporto multi-documento è importante qui - un pacchetto Kubernetes di sei risorse diventa un array JSON che puoi iterare.

Apparecchi per prove edili

I test di integrazione spesso necessitano di un oggetto config piuttosto che di un file config La conversione del manifesto reale in JSON ti dà un dispositivo che è garantito per corrispondere alla forma di produzione, che è un punto di partenza di gran lunga migliore rispetto a un oggetto che hai digitato dalla memoria Abbinalo a JSON a dattiloscritto e il tuo apparecchio viene fornito con tipi.

Revisione della configurazione in una richiesta pull

I difetti di YAML fortemente ancorato sono difficili da leggere perché un cambio di una riga in un ancoraggio cambia silenziosamente ogni consumatore Convertendo entrambe le versioni con Ordina tasti abilitato e diffondendo il JSON mostra il raggio di esplosione reale: ogni valore risolto che è cambiato, non solo la riga che è stata modificata.

Migrazione tra strumenti

Molte piattaforme accettano JSON ma non YAML, o viceversa La conversione è solitamente l'intera migrazione Quando è necessario tornare indietro - JSON alla mano, YAML richiesto - il Convertitore JSON a YAML chiude il ciclo e il Condivisore di yam conferma le analisi dei risultati prima di commetterlo.

YAML e JSON a confronto

Dimensione	igname	json
commentario	certo	no
Montaggio umano	Basato sull'indentazione, facile da scremare	Punteggiatura-pesante, verboso
Analisi della macchina	Più lento, parser più grandi, più casi di bordo	Parser veloci e minuscoli ovunque
Tipo Descrizione	Implicito, dipendente dallo schema	Esplicito dalla sintassi
referenze	Ancoraggi, alias, unire le chiavi	nessuno
Più documenti per file	Sì, via ---	no
Casa tipica	Config file, pipeline CI, manifesti	API, scambio dati, archiviazione

YAML 1.2 è formalmente un superset di JSON, quindi ogni documento JSON è già valido YAML Non è vero il contrario, motivo per cui convertire YAML in JSON è un'operazione con perdita esattamente in una direzione: i commenti e la struttura di riferimento vengono scartati, mentre i dati vengono conservati Se il tuo YAML ha commenti a cui tieni, mantieni lo YAML come fonte di verità e tratta il JSON come un artefatto derivato.

Privacy: perché viene eseguito nel tuo browser

I file di configurazione sono tra gli artefatti in testo semplice più sensibili di un team. Portano nomi host interni, nomi di cluster, percorsi di registro, account di servizio, identificatori di database e, nonostante tutti, le migliori intenzioni di & #39; - le credenziali occasionali che non sono ancora diventate un gestore segreto.

Il convertitore è JavaScript lato client Il tuo documento è analizzato nella pagina, il JSON è prodotto nella pagina e nessuna richiesta trasporta i tuoi dati da nessuna parte Carica lo strumento una volta e continua a funzionare con la rete spenta, che è un'abitudine ragionevole per qualsiasi cosa in cui incolli un manifesto Questo è lo stesso principio dietro ogni strumento sul sito, e il ragionamento è spiegato nella guida su Privacy dei dati negli strumenti online. Se stai assemblando un toolkit per browser di uso generale, il Toolkit per sviluppatori web la guida copre cos'altro vi appartiene.

Limitazioni che vale la pena conoscere

Nessun convertitore che si adatta a una scheda del browser implementa ogni angolo delle specifiche YAML ed è più utile essere specifici sui bordi piuttosto che implicare che non ce ne siano.

Chiavi di mappatura complesse: l'esplicito ? key modulo in cui il tasto è esso stesso una sequenza o una mappatura - non sono supportati, perché i tasti oggetto JSON devono essere stringhe Digitare tag come !!binary o personalizzato !MyType le direttive non vengono interpretate; il valore arriva come testo I valori speciali del float .inf, -.inf, e .nan sono conservati come stringhe, poiché JSON non ha letterali per loro e si converte silenziosamente in null perderebbe più informazioni di quante ne risparmiano Direttive come %YAML 1.2 vengono ignorati piuttosto che messi in pratica.

Nessuno di questi appare nei normali file Kubernetes, Compose, Actions o Ansible Se ne premi uno, stai lavorando con un documento scritto per un linguaggio specifico's libreria YAML, e quel library's own dumper è lo strumento giusto.

FAQ

Come faccio a convertire YAML in JSON online?

Incolla il tuo YAM nel pannello di input e fai clic su Converti. Il parser legge il documento, risolve gli ancore e blocca gli scalari e stampa JSON formattato che puoi copiare o scaricare. Tutto accade nel tuo browser, quindi nessun file viene caricato.

JSON è un sottoinsieme di yaml?

si. YAML 1.2 è stato ridefinito come un rigoroso superset di JSON, quindi qualsiasi documento JSON valido è anche YAML valido. Il contrario non è vero: YAML aggiunge commenti, ancore, blocchi scalari, più documenti per file e chiavi non string, nessuno dei quali JSON può esprimere direttamente.

Come vengono convertiti gli ancore e gli alias YAML in JSON?

JSON non ha sintassi di riferimento, quindi ogni alias viene espanso in una copia completa del valore definito dal suo ancoraggio Una configurazione che riutilizza un blocco predefinito tre volte produce tre oggetti JSON identici L'output è quindi più grande del sorgente YAML ma semanticamente identico.

Cosa succede per unire le chiavi come la staffa a doppio angolo?

La mappatura di riferimento viene unita all'oggetto corrente. Chiavi scritte esplicitamente nella vincita della mappatura figlio su chiavi unite, che corrispondono al comportamento della specifica MErge-Key YAM e di Kubernetes e Ansible Tooling.

Perché il mio YAML ha fallito con un errore di schede?

YAML vieta i caratteri di scheda per il rientro: la specifica consente solo spazi. Gli editor che inseriscono le schede su Invio sono la causa abituale Convertire le schede iniziali in spazi, cosa che la maggior parte degli editor può fare per un intero file contemporaneamente, e il documento verrà analizzato.

Posso convertire un file YAML multi-documento con separatori di documenti?

Sì. Ogni documento tra i marcatori separatori viene analizzato in modo indipendente e il risultato è un array JSON con un elemento per documento, in ordine di origine Un file a documento singolo restituisce l'oggetto stesso, non un array a un elemento.

I numeri di porta e le stringhe di versione manterranno il loro tipo?

Gli scalari semplici vengono risolti dallo schema core YAML, quindi un 8080 non quotato diventa il numero 8080 e un 1.10 non quotato diventa 1.1. Citare il valore nel tuo YAML per mantenerlo una stringa o attivare l'opzione Mantieni stringhe per disattivare tutta la coercizione scalare.

Come si convertono gli scalari a blocchi letterali e piegati?

Un blocco letterale mantiene ogni nuova riga, quindi diventa una stringa JSON con interruzioni di riga sfuggite Un blocco piegato unisce linee consecutive con uno spazio e tratta le linee vuote come interruzioni di paragrafo Gli indicatori di compressione sono rispettati: un meno fa cadere la nuova riga finale e un più mantiene ogni riga vuota finale.

---