Formattatore e validatore YAML

Incolla YAML per formattarlo e validarlo. Vedi gli errori all'istante, correggi l'indentazione e converti in JSON.

Elaborato localmente · niente viene inviato a un server
Incolla YAML per validare

Cos'è YAML?

YAML (YAML Ain't Markup Language) è un formato di serializzazione dei dati leggibile dall'uomo, usato per i file di configurazione (Docker, Kubernetes, GitHub Actions, Ansible), lo scambio di dati e altro ancora. Usa l'indentazione invece delle parentesi graffe ed è un superinsieme di JSON.

Domande frequenti

Quali errori rileva il validatore?

Errori di indentazione, due punti mancanti, chiavi duplicate, caratteri non validi, stringhe non chiuse, annidamenti errati e altri problemi di sintassi YAML. I messaggi di errore includono i numeri di riga.

Posso convertire YAML in JSON?

Sì! Clicca sul pulsante «→ JSON» per convertire il tuo YAML in JSON ben formattato. Per la conversione inversa, usa il nostro Convertitore JSON in YAML.

Una rapida panoramica di YAML

YAML 1.0 fu pubblicato nel 2001 da Clark Evans, Ingy döt Net e Oren Ben-Kiki; YAML 1.1 seguì nel 2005, e la versione attuale è YAML 1.2.2, che ha corretto diversi tranelli storici (in particolare il «problema della Norvegia», vedi sotto) ed è stato progettato per essere un sovrainsieme stretto di JSON. La specifica ufficiale si trova su yaml.org/spec/1.2.2. Questo formattatore usa la libreria open source js-yaml, che analizza rispetto allo schema YAML 1.2 per impostazione predefinita, quindi la maggior parte delle stranezze legacy della 1.1 non si applica al testo formattato qui, ma si applicano alla maggior parte degli strumenti YAML lato server a cui invierai l'output.

Dove vive davvero YAML

YAML ha vinto come formato di configurazione per l'infrastruttura cloud-native. I posti dove lo incontrerai più spesso:

La trappola degli spazi bianchi (solo spazi)

YAML usa l'indentazione per indicare la struttura, e la specifica è esplicita sul fatto che i tab non sono ammessi per l'indentazione. Solo spazi. Questa è la singola fonte più comune di bug nello YAML scritto a mano, specialmente perché molti editor mescolano silenziosamente tab e spazi a seconda delle loro impostazioni. Il messaggio di errore che otterrai da un parser rigoroso è del tipo «found character '\t' that cannot start any token», traduzione: «hai usato un tab da qualche parte.» La soluzione è universale: abilita «mostra spazi bianchi» nel tuo editor e converti ogni tab in due o quattro spazi.

La dimensione dell'indentazione è una convenzione anziché una regola della specifica. 2 spazi è lo standard di fatto per i manifesti Kubernetes, GitHub Actions e la maggior parte dello YAML che leggerai sul web moderno. 4 spazi è più comune in Ansible. La regola che conta: sii coerente all'interno di un singolo file. Mescolare 2 e 4 spazi tra chiavi di pari livello è ciò che manda in tilt i parser, non quale dimensione scegli.

Il problema della Norvegia (e perché dovresti virgolettare le stringhe ambigue)

YAML 1.1 (ancora il valore predefinito in PyYAML, snakeyaml e molti altri parser lato server) interpreta una lunga lista di grafie booleane non virgolettate come booleani veri e propri: true, True, TRUE, false, False, FALSE, yes, Yes, YES, no, No, NO, y, n, on, off. Il famoso tranello: il codice ISO del paese per la Norvegia è NO. Una configurazione YAML che elenca i paesi come stringhe non virgolettate analizza silenziosamente la Norvegia come il booleano false, e il codice a valle che legge countries[0] == 'NO' fallisce in modo confuso.

YAML 1.2 (e lo schema predefinito di js-yaml) ha limitato i booleani a soli true / false, il che corregge il problema della Norvegia a livello di parser. Ma molti strumenti del mondo reale impostano ancora come predefinito lo schema YAML 1.1 per retrocompatibilità. L'abitudine difensiva: virgoletta qualsiasi stringa che potrebbe sembrare un booleano, un numero, una data o una versione. country: "NO", postal_code: "01234", version: "1.10", time: "10:30". Le virgolette sono il disambiguatore universale.

Altri tranelli della coercizione di tipo

Stile a blocchi contro stile a flusso

YAML supporta due notazioni per gli stessi dati:

# Block style (the standard, indentation-based)
person:
  name: Alice
  tags:
    - admin
    - billing

# Flow style (JSON-like inline)
person: { name: Alice, tags: [admin, billing] }

Lo stile a blocchi è ciò che vedrai nel 99% dello YAML scritto a mano, è ciò che rende leggibile il formato. Lo stile a flusso è una comoda via di fuga per valori brevi su una sola riga o per generare YAML a livello di codice dove preferiresti non tenere traccia dell'indentazione. Il formattatore normalizza allo stile a blocchi per l'output (la forma più leggibile) indipendentemente da quale stile abbia usato il tuo input.

Àncore e alias (il trucco DRY)

La funzione di riusabilità di YAML: definisci un valore una volta con l'àncora &name, riferiscilo altrove con l'alias *name. Comodo per i file di configurazione lunghi dove lo stesso blocco di valori appare più volte.

defaults: &defaults
  region: us-east-1
  log_level: info

production:
  <<: *defaults
  log_level: warn   # override

staging:
  <<: *defaults

Alcune avvertenze: non tutti i processori YAML supportano àncore e alias (in particolare alcuni vecchi strumenti per manifesti Kubernetes e certi contesti Helm). La sintassi <<: «merge key» mostrata sopra è un'estensione di YAML 1.1 ed è ufficialmente deprecata nella 1.2, js-yaml la supporta, ma i parser puri 1.2 potrebbero non farlo.

File multi-documento

Un singolo file YAML può contenere più documenti, separati da ---. Comune in Kubernetes, un file con un Deployment, un Service e un ConfigMap, separati da ---, applicati con un solo kubectl apply -f:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
---
apiVersion: v1
kind: Service
metadata:
  name: app-svc

YAML contro JSON contro TOML

Se hai una scelta per una nuova configurazione: TOML per la configurazione piatta, YAML se hai bisogno di un annidamento profondo e l'ecosistema si è standardizzato su di esso (Kubernetes, Ansible), JSON se la scrive una macchina. YAML è il formato giusto quando gli umani devono leggere configurazioni profondamente annidate e scrivere commenti significativi in linea.

Privacy

Le configurazioni YAML contengono spesso segreti che non dovrebbero passare per il server di qualcun altro: blob base64 dei Secret di Kubernetes, password di database nell'application.yml, chiavi API nei workflow CI, nomi host interni nelle configurazioni di distribuzione. Il formattatore funziona interamente nel tuo browser tramite la libreria open source js-yaml, il contenuto incollato viene analizzato e riemesso localmente, senza recupero / senza caricamento / senza registrazione. Chiudere la scheda cancella tutto.

Errori comuni

  1. Mescolare tab e spazi nell'indentazione. L'errore più comune. I tab sono vietati dalla specifica; alcuni editor li inseriscono silenziosamente. Mostra gli spazi bianchi nel tuo editor.
  2. Indentazione incoerente tra elementi di pari livello. Le chiavi di pari livello devono essere allineate alla stessa colonna. Un'indentazione mista di 2/4 spazi rompe l'analisi.
  3. Valori non virgolettati che sembrano booleani, numeri, date o orari. NO, 012, 1.10, 10:30, yes: virgolettali.
  4. Spazio mancante dopo i due punti. key: value funziona; key:value non è valido (analizzato come una singola stringa).
  5. Spazi bianchi finali. Alcuni parser trattano gli spazi finali come significativi; altri no. L'abitudine sicura tra strumenti diversi è rimuovere gli spazi bianchi finali.
  6. Stringhe multi-riga senza il giusto scalare a blocchi. Le stringhe lunghe hanno bisogno di | (letterale, preserva i ritorni a capo) o > (ripiegato, unisce le righe). Il testo multi-riga semplice non virgolettato raramente si comporta come ti aspetti.
  7. Àncore / alias dati per scontati ovunque. Helm e alcuni contesti Kubernetes non supportano pienamente &/*. Fai delle prove nella tua vera pipeline prima di dipendere da essi.
  8. Discordanze di codifica. I file YAML dovrebbero essere UTF-8. Un editor Windows che salva come UTF-16 con BOM produce file che alcuni parser non riescono a leggere.

Altre domande frequenti

Il formattatore preserverà i miei commenti?

No. La libreria js-yaml analizza lo YAML in un valore JavaScript e lo riemette da quel valore, il che significa che i commenti (# like this) vengono eliminati, vivono nel testo sorgente, non nella struttura analizzata. Se preservare i commenti è importante (di solito lo è per i file di configurazione curati a mano), usa un'alternativa che preserva i commenti come eemeli/yaml tramite la sua API CST, oppure fai piccole modifiche a mano anziché far passare il file per questo formattatore.

Perché il mio NO viene trattato come un booleano dal parser YAML del mio server?

Perché quel parser sta usando YAML 1.1 (il valore predefinito per PyYAML, snakeyaml e molti altri), che interpreta NO come il booleano false. Questo formattatore usa YAML 1.2 per impostazione predefinita (tramite js-yaml) quindi non scatena il bug qui, ma nel momento in cui spedisci il file in un ambiente YAML 1.1 il tranello si attiva. Virgoletta sempre le stringhe ambigue: country: "NO".

Posso convertire YAML in JSON?

Sì, fai clic su «→ JSON». La conversione è senza perdita per tutto ciò che può essere rappresentato in JSON (stringhe, numeri, booleani, null, array, oggetti). Le cose che non sopravvivono: i commenti (JSON non ha una sintassi per essi), le àncore e gli alias (JSON non ha un equivalente), e i tipi data / timestamp di YAML (che diventano stringhe in JSON). Per la direzione inversa, usa lo strumento dedicato da JSON a YAML.

Viene inviato qualcosa a un server?

No. Tutta l'analisi, la formattazione e la conversione in JSON vengono eseguite nel tuo browser tramite js-yaml. Lo YAML incollato non viene mai trasmesso a nessun server. Questo è importante perché le configurazioni YAML contengono spesso segreti (valori dei Secret di Kubernetes, password di database, chiavi API, endpoint interni) che non dovrebbero essere caricati su un servizio di terze parti.

Qual è il limite di dimensione?

Nessun limite rigido, il formattatore funziona nella memoria del tuo browser. I manifesti Kubernetes tipici (pochi KB) e i chart Helm (decine di KB) si formattano istantaneamente. I file multi-documento molto grandi (diversi MB) possono essere lenti ma generalmente funzionano; se hai un chart Helm da 10 MB, formattalo localmente con uno strumento da riga di comando.

Perché YAML è così soggetto a errori?

Tre ragioni che si sommano: (1) gli spazi bianchi significativi fanno sì che i refusi causino cambiamenti semantici silenziosi; (2) la permissiva coercizione di tipo di YAML 1.1 trasforma stringhe ambigue in booleani / numeri non voluti; (3) il formato ha troppi modi di scrivere la stessa cosa (a blocchi contro a flusso, virgolette singole contro doppie, tre varianti di stringhe multi-riga. Le abitudini difensive) virgoletta sempre, sii sempre coerente con l'indentazione, valida prima di distribuire, correggono gran parte della superficie esposta.

Strumenti correlati

Convertitore JSON → YAML

Converti tra i formati JSON e YAML.

Formattatore JSON

Formatta, valida e abbellisce i dati JSON.

Formattatore XML

Formatta, abbellisce o minifica XML.