Due formati, ruoli che si sovrappongono
JSON (JavaScript Object Notation) e YAML (YAML Ain’t Markup Language) rappresentano entrambi dati strutturati: oggetti annidati, liste, stringhe, numeri e booleani. Compaino in API, file di configurazione, pipeline CI, manifest Kubernetes ed esempi di documentazione. Scegliere tra loro non è tanto una questione di quale sia «migliore», quanto di chi modifica il file, quali strumenti lo consumano e quanto rigoroso deve essere il parsing.
Se hai già JSON e vuoi ispezionarlo come indentazione YAML, converti con JSON a YAML.
JSON in breve
JSON nasce dalla sintassi dei letterali oggetto di JavaScript ed è diventato un formato di scambio indipendente dal linguaggio. Un documento JSON è costruito da:
- Oggetti:
{ "key": "value" } - Array:
[1, 2, 3] - Stringhe tra virgolette doppie
- Numeri
true,falseenull
Vincoli rilevanti: niente commenti, niente virgole finali in JSON standard, le chiavi devono essere stringhe e le stringhe usano una sintassi di escape limitata. Questi vincoli rendono i parser semplici e rigorosi—preziosi quando le macchine scambiano dati.
Il JSON formattato è leggibile per documenti piccoli. Configurazioni grandi con annidamento profondo diventano rumorose per graffe, parentesi quadre e chiavi quotate a ogni riga.
YAML in breve
YAML privilegia la modifica umana. La struttura è per lo più trasmessa dall’indentazione piuttosto che dalle graffe. Tra le funzionalità:
- Commenti che iniziano con
# - Stringhe non quotate in molti casi
- Anchors e alias per il riuso
- Flussi multi-documento separati da
--- - Tag di tipo espliciti nell’uso avanzato
Un piccolo mapping appare così:
service:
name: api
replicas: 3
ports:
- 8080
- 8443
La stessa struttura in JSON ripete punteggiatura e virgolette. Per gli operatori che modificano manifest ogni giorno, la brevità di YAML è attraente.
Sovrapposizione del modello dati
Nel nucleo, entrambi i formati possono esprimere alberi di map e sequenze con foglie scalari. Il round-trip è spesso possibile per il sottoinsieme comune: oggetti, array, stringhe, numeri, booleani e null.
Le differenze emergono ai margini:
- YAML può produrre chiavi non-stringa; JSON no.
- YAML ha più modi di scrivere stringhe (blocchi letterali, blocchi folded).
- Il «Norway problem» di YAML e altri quirk di tipizzazione implicita possono trasformare
NO,ono token simili a versioni non quotati in booleani o numeri a seconda della versione YAML e del parser. - I numeri JSON sono lineari; YAML può interpretare in modo speciale interi grandi o timestamp in alcuni loader.
Quando conta l’interop, preferisci quotare in YAML le stringhe che sembrano booleani, numeri o date, oppure genera YAML da una struttura tipizzata invece di modificare a mano scalari ambigui.
Commenti e documentazione
JSON non ha commenti standard. I team a volte abusano di campi "_comment", che inquinano gli schema. I commenti # di YAML documentano l’intento accanto ai dati—perché il conteggio delle replica è 3, quale team possiede una label—senza cambiare il modello informativo.
Se il pubblico principale sono macchine (API, body di fetch nel browser), la mancanza di commenti di JSON raramente è un problema. Se gli esseri umani mantengono il file per mesi, i commenti YAML riducono la perdita di conoscenza tribale.
Tooling ed ecosistema
Punti di forza di JSON
- Parser ubiqui in quasi ogni linguaggio mainstream
- Supporto browser di prima classe (
JSON.parse/JSON.stringify) - Ecosistemi di schema (JSON Schema) ampiamente adottati
- Diff orientati alle righe familiari, anche se pieni di graffe
- Parser in streaming per payload grandi
Punti di forza di YAML
- Dominante in DevOps (Kubernetes, Ansible, molti sistemi CI)
- Merge e anchors (potenti, a volte abusati)
- File multi-documento per raggruppare risorse correlate
- Più amichevole per configurazioni poco annidate
Rischi di YAML
- Complessità della specifica (differenze YAML 1.1 vs 1.2)
- Errori di indentazione difficili da vedere
- Funzionalità (custom tags, merge keys) che riducono la portabilità
- Esecuzione accidentale di codice in loader non sicuri storicamente—usa sempre API di load sicuro
Prestazioni e dimensione
Per i protocolli di rete, JSON è di solito più economico da parsare in librerie native ottimizzate e evita il costo dell’indentazione. JSON e YAML compressi convergono in dimensione. Per configurazioni lette di rado e modificate spesso, la velocità di parsing raramente è il collo di bottiglia; lo è il tasso di errore umano.
I cugini binari (MessagePack, CBOR, Protobuf) superano entrambi quando domina il throughput. Non sono formati umani di sostituzione diretta.
Strategie di conversione
Convertire JSON → YAML è tipicamente senza perdita per il sottoinsieme comune e utile per le review di leggibilità. Convertire YAML → JSON può perdere commenti, anchors e tipi non JSON. Tratta la conversione come una proiezione, non come un archivio perfetto dell’intento dell’autore.
Consigli di workflow:
- Mantieni un’unica fonte di verità (spesso JSON Schema o un modello tipizzato nel linguaggio).
- Genera il formato di cui ogni consumatore ha bisogno.
- Se gli umani devono modificare YAML, valida contro uno schema a ogni modifica.
- Evita di mantenere a mano due copie dello stesso documento.
Il convertitore from-json di Tool Plaza ti aiuta a vedere come appare un payload JSON con sintassi basata sull’indentazione.
Quando scegliere JSON
- API HTTP pubbliche e body di webhook
- Client browser e mobile
- Scambio macchina rigoroso con ambiguità minima
- Logging di eventi strutturati verso aggregatori che si aspettano JSON lines
- Embedding in linguaggi dove i letterali JSON mappano in modo pulito sui tipi nativi
Quando scegliere YAML
- Manifest di deployment e infrastruttura modificati da persone
- File di config che beneficiano dei commenti
- Ecosistemi già standardizzati su YAML
- Documenti in cui la chiarezza di indentazione batte l’abbinamento delle graffe per il tuo team
Approcci ibridi
Alcuni progetti memorizzano JSON canonico nel controllo di versione e generano YAML per uno strumento specifico. Altri accettano input YAML, normalizzano a un AST interno ed emettono JSON per le API. Entrambi funzionano se la pipeline è automatizzata e testata.
Sii cauto con le estensioni «JSON5» o «JSONC» (JSON con commenti): migliorano l’ergonomia ma non sono universali. Documenta il dialetto se ne adotti uno.
Igiene di editing e review
- Usa editor che evidenziano indentazione e spazi finali per YAML.
- Fai fallire la CI su sintassi non valida prima del merge.
- Preferisci indentazione a 2 spazi in modo coerente nei team YAML.
- Mantieni le righe ragionevolmente corte; le stringhe inline enormi appartengono a blocchi letterali o file esterni.
- Non incollare secret in nessuno dei due formati in repo pubblici—usa secret manager e riferimenti.
Riepilogo
JSON è il formato di scambio rigoroso e ubiquo; YAML è il dialetto di configurazione amico dei commenti, con sintassi più ricca—e più rischiosa. Condividono un modello dati annidato per map e liste quotidiane. Scegli JSON per API e macchine, YAML per file di infra gestiti da umani, e converti deliberatamente quando ti servono entrambe le viste della stessa struttura.