YAML vs JSON — quando usare quale, e perché la maggior parte dei team usa entrambi

Se hai mai aperto un manifsto Kubernetes, un workflow GitHub Actions o un file docker-compose, hai usato YAML. Se hai mai chiamato un’API REST o scritto un file di configurazione per un progetto Node.js, hai usato JSON. Sono entrambi formati di serializzazione. Descrivono entrambi gli stessi tipi di strutture dati — mappe, array, stringhe, numeri, booleani, null. Allora perché ne abbiamo due?

La risposta breve: YAML ottimizza per gli esseri umani, JSON ottimizza per le macchine. La risposta lunga coinvolge qualche decennio di esperienza degli sviluppatore, qualche riunione di commissione e una quantità sorprendente di casi limite. Vediamola.

Cosa fa bene JSON

JSON (JavaScript Object Notation) è diventato popolare nei primi anni 2000 come formato di payload per le richieste AJAX. Era volutamente piccolo — sei tipi di valore, nessun commento, nessuna virgola finale, nessuna ambiguità. Quella rigidità è la sua superpotenza sulla rete:

• I parser sono piccoli e veloci. JSON.parse è integrato in ogni browser e in ogni runtime. Non c’è nulla da pensare.
• Gli errori sono inconfondibili. Quando JSON è rotto, il parser ti dice esattamente quale riga e colonna.
• Le macchine concordano sulla semantica. Un numero è un numero, una stringa è una stringa, true è true. Non c’è il dibattito “è yes un booleano o una stringa?”

Per questo JSON è la lingua franca delle API. Quando due servizi parlano, vuoi il formato con meno sorprese.

Cosa fa bene YAML

YAML (YAML Ain’t Markup Language) è stato progettato per file di configurazione scritti da esseri umani. Ha sacrificato parte della rigidità di JSON per la leggibilità:

• Nessuna parentesi graffa, nessuna parentesi quadra. La struttura è l’indentazione. Un docker-compose.yml si legge dall’alto in basso come una lista.
• Commenti. Un # inizia un commento. JSON non ha sintassi per i commenti — e la mancanza di commenti è il motivo più comune per cui le squadre passano da JSON a YAML per i file di configurazione.
• Ancore e riferimenti. &anchor e *reference ti permettono di definire un valore una volta e riutilizzarlo. JSON non ha equivalente; devi copiare e incollare.
• Stringhe multi-riga. I blocchi letterali (|) e i blocchi piegati (>) gestiscono testo e codice senza gestire escape.

Per questo YAML domina nei posti dove gli esseri umani leggono e scrivono a mano: Kubernetes, GitHub Actions, GitLab CI, playbook Ansible, docker-compose, CloudFormation, specifiche OpenAPI e l’ondata del 2025 di file di configurazione per agenti AI (.github/agents.yml, manifesti server MCP, evaluation harness).

L’asimmetria

Ecco il segreto sporco: YAML è un superset del modello dati di JSON. Ogni file JSON valido può essere espresso come YAML, ma il contrario non è vero. YAML ha funzionalità che JSON semplicemente non ha — commenti, ancore, file multi-doc, tag personalizzati. Una volta che scrivi YAML con ancore, non puoi convertirlo indietro in JSON senza perdita. Le ancore spariscono.

Questo conta per gli strumenti. Se hai un file YAML con &defaults *defaults, la conversione in JSON espanderà i riferimenti (produrrà silenziosamente un file più grande) o li eliminerà (produrrà silenziosamente un file più piccolo). Lo stesso vale per i commenti. JSON non ha dove metterli.

Quando usare quale

Usa JSON quando:

• Stai inviando dati sulla rete (API, code di messaggi, payload di eventi).
• Il file è letto dal codice, non dagli esseri umani.
• Vuoi messaggi di errore inconfondibili da parser rigidi.
• Stai ottimizzando per la velocità di analisi su dispositivi vincolati.

Usa YAML quando:

• Un essere umano è il principale autore e lettore del file.
• Vuoi commenti per spiegare l’intento.
• Vuoi riutilizzare blocchi di configurazione con ancore.
• Gli strumenti nel tuo dominio lo prevedono (Kubernetes, CI, ecc.).

La risposta pragmatica per la maggior parte delle squadre: JSON per la rete, YAML per la configurazione, entrambi per lo scambio dati. In caso di dubbio, memorizza la versione canonica in JSON (senza perdita) e produci YAML per il consumo umano (con commenti e ancore) solo quando il pubblico è uno sviluppatore che apre un editor di testo.

Errori comuni durante la conversione tra i due

1. Numeri e booleani sono tipizzati automaticamente in YAML. port: 8080 è un numero. port: "8080" è una stringa. Dimenticare di mettere le virgolette può cambiare il tuo tipo.
2. Le ancore e i commenti vengono eliminati in JSON. Nessun modo per aggirare — il formato non ha dove metterli.
3. YAML null è ambiguo. key: (valore vuoto) è null. key: null è anche null. key: "" è una stringa vuota. Tre cose diverse.
4. Le tab rompono YAML. L’indentazione deve essere con spazi. Le tab sono un errore.
5. YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1 trattava yes, no, on, off come booleani. YAML 1.2 (la specifica usata da js-yaml, PyYAML e la maggior parte dei parser nel 2026) no. La release di manutenzione 1.2.2 nel 2025 ha raffinato alcuni casi limite attorno ai marcatori di fine documento e alla gestione del BOM — la maggior parte dei parser ha adottato le correzioni silenziosamente. Se stai passando da un codebase del 2018, la tua configurazione potrebbe ancora rompersi in modi sottili.

Strumenti che aiutano

Quando passi da uno all’altro — e lo farai, perché ogni squadra usa entrambi — un convertitore lato client veloce è il tuo amico. Gli strumenti YAML to JSON e JSON to YAML su DevSpeedTools funzionano interamente nel tuo browser, quindi file di configurazione con segreti non lasciano mai la tua macchina. Apri DevTools → Network e vedrai zero richieste con i tuoi dati.

Per YAML che è diventato disordinato nel tempo, il formattatore YAML normalizzerà l’indentazione a due spazi e correggerà le virgolette incoerenti. Per i file che non si analizzano, il validatore YAML ti mostra la riga e colonna esatta di ogni errore.

La conclusione: smetti di trattare YAML e JSON come formati in competizione. Sono complementari. Il formato giusto dipende da chi sta leggendo il file — una macchina, o uno sviluppatore stanco alle 23 che sta cercando di capire perché il suo deployment è rotto.