JSON vs YAML vs XML: sintassi, usi e come convertire dall'uno all'altro

JSON, YAML e XML sono formati di testo semplice per dati strutturati. Con le stesse informazioni, tutti e tre le descrivono fedelmente, ma nella pratica ognuno si è ritagliato il proprio territorio: JSON nelle API, YAML nei file di configurazione, XML nei documenti e nei sistemi aziendali. Capire il perché ti aiuta a scegliere quello giusto e a evitare sorprese quando converti.

Gli stessi dati in tre formati

Ecco la definizione di un piccolo servizio scritta in tre modi. Prima in JSON:

{
  "service": "web",
  "port": 8080,
  "debug": false,
  "tags": ["api", "public"]
}

La stessa cosa in YAML:

# web service
service: web
port: 8080
debug: false
tags:
  - api
  - public

E in XML:

<?xml version="1.0" encoding="UTF-8"?>
<service name="web">
  <port>8080</port>
  <debug>false</debug>
  <tags>
    <tag>api</tag>
    <tag>public</tag>
  </tags>
</service>

Alcune differenze saltano subito all'occhio:

• JSON usa graffe, parentesi quadre e virgolette. È rigoroso: niente commenti, niente virgole finali, chiavi sempre tra virgolette doppie.
• YAML si affida all'indentazione invece che alle parentesi e ammette commenti con #. È il più compatto e il più facile da leggere a colpo d'occhio.
• XML racchiude ogni valore tra tag di apertura e chiusura e può aggiungere attributi agli elementi (name="web"). È il più prolisso, ma anche il più espressivo.

JSON: la lingua delle API

JSON corrisponde direttamente agli oggetti e agli array di quasi ogni linguaggio di programmazione, ed è per questo che è diventato il formato predefinito delle API web. I parser sono veloci, integrati nei browser e nelle librerie standard, e la grammatica è così ridotta che ci sono pochissimi modi di fraintendere un documento.

Il suo rigore è un vantaggio per le macchine e un piccolo fastidio per le persone. Non puoi lasciare un commento per spiegare un'impostazione, e una sola virgola mancante rompe l'intero file. Per questo JSON funziona al meglio quando lo scrive un programma e lo legge un altro: risposte delle API, log, esportazioni di dati, package.json.

YAML: configurazione scritta dalle persone

YAML è stato progettato per essere scritto e rivisto dalle persone. Ecco perché tanti strumenti DevOps l'hanno scelto: i manifest di Kubernetes, i workflow di GitHub Actions e i file di Docker Compose sono in YAML. Commenti, stringhe su più righe e l'assenza di punteggiatura rendono piacevole la manutenzione di file di configurazione lunghi.

Il prezzo sono le sottigliezze. L'indentazione ha un significato, quindi uno spazio fuori posto cambia la struttura. E YAML deduce i tipi dai valori senza virgolette, il che porta alle sue trappole più famose:

country: NO      # YAML 1.1: false
version: 1.10    # 1.1 (number)
zip: 01234       # 1234 or octal

Con le regole di YAML 1.1, ancora usate da molti parser, NO, yes, on e off diventano booleani. I numeri perdono gli zeri finali e gli zeri iniziali possono essere letti come ottale. La soluzione è semplice: metti tra virgolette tutto ciò che deve restare una stringa.

country: "NO"
version: "1.10"
zip: "01234"

XML: documenti, schemi e feed aziendali

XML è più vecchio degli altri due e offre funzionalità che a loro mancano: namespace per combinare vocabolari, schemi (XSD) per validare rigorosamente la struttura, attributi e contenuto misto in cui testo e tag si alternano. Questo lo rende adatto ai documenti e ai sistemi in cui conta un contratto formale: feed RSS e Atom, servizi SOAP, standard di fatturazione e bancari, immagini SVG, il pom.xml di Maven e i file contenuti in un DOCX o in un XLSX.

Se stai costruendo qualcosa di nuovo e devi solo scambiare dati, XML è raramente la prima scelta. Ma continuerai a riceverlo da partner, sistemi legacy e fonti di dati pubbliche, quindi saperlo trasformare in JSON è un'abilità molto pratica.

Confronto rapido

• Leggibilità: YAML > JSON > XML.
• Rigore e prevedibilità: JSON e XML non sono ambigui; YAML dipende dall'indentazione e dalla deduzione dei tipi.
• Commenti: sì per YAML e XML, no per JSON.
• Validazione: XML ha gli strumenti di schema più maturi; JSON Schema è molto diffuso; anche YAML di solito si valida con JSON Schema.
• Ambiente tipico: JSON per API e dati, YAML per la configurazione, XML per documenti e integrazione aziendale.

Convertire dall'uno all'altro: a cosa fare attenzione

Dato che tutti e tre descrivono alberi di dati, la conversione è di solito semplice. Alcuni dettagli però vanno conosciuti:

• Da YAML a JSON si perdono i commenti. JSON non ha dove conservarli. Ancore e alias (& e *) vengono espansi in copie normali.
• Da JSON a YAML non si perde nulla. Ogni JSON valido può essere espresso in YAML; in YAML 1.2, JSON è quasi un sottoinsieme di YAML.
• Gli attributi XML richiedono una convenzione. JSON non ha attributi, quindi i convertitori li salvano come chiavi normali, spesso con un prefisso come @. Controlla il risultato prima di passarlo a un altro programma.
• Elemento singolo o lista. In XML, un <tag> e tre <tag> si scrivono allo stesso modo. In JSON uno può diventare un oggetto e gli altri un array, quindi il codice che usa il risultato deve gestire entrambi i casi.
• In XML è tutto testo. 8080 e false sono solo caratteri tra tag; passando da XML a JSON potresti doverli riconvertire in numero o booleano.
• Da JSON a XML serve un'unica radice e chiavi che siano nomi di elemento validi (senza spazi e senza iniziare con una cifra).

Converti nel tuo browser

I convertitori di dati di Azpy funzionano interamente nel tuo browser: incolla il testo o trascina un file e il risultato compare all'istante senza caricare nulla. Puoi quindi usarli in tutta tranquillità con file di configurazione che contengono nomi di server interni o risposte di API con dati dei clienti. Trovi JSON in YAML, YAML in JSON, XML in JSON e JSON in XML tra gli strumenti.

Una regola pratica

Macchine che parlano con macchine → JSON. Persone che modificano configurazioni → YAML, con le virgolette attorno a tutto ciò che è ambiguo. Documenti, schemi rigorosi o un contratto aziendale esistente → XML. E quando il formato che hai non è quello che ti serve, convertilo e controlla i casi limite descritti sopra.