Convertire JSON in XML

Un documento XML ha un singolo elemento più esterno. Un documento JSON può essere un oggetto con quindici chiavi, oppure un array, oppure un numero puro, e nessuno di questi casi porta con sé un nome per il contenitore. La conversione ha quindi una regola : un oggetto con una sola chiave usa quella chiave come radice, e tutto il resto viene avvolto in un elemento chiamato root. L’eccezione merita di essere ricordata perché riguarda una delle forme più comuni : se quella singola chiave contiene un array, {"items" :[1,2]} usarla come radice produrrebbe <items> scritto due volte, un documento senza un elemento più esterno, e allora <root> viene invece avvolto attorno alla coppia.

Il primo caso è quello a cui puntare, ed è una piccola modifica al JSON se lo si controlla. Avvolgere il payload in una singola chiave che lo descriva — invoice, order, shipment — significa che l’XML esce con il nome di elemento che il sistema ricevente si aspetta, invece di un wrapper generico che poi si deve rinominare nell’output.

XML non ha un tipo array e non ne ha mai avuto bisogno : una lista è lo stesso tag scritto più volte nello stesso genitore. Un oggetto che contiene tre tag produce tre elementi <tags> di fila, che è esattamente la forma che ogni consumatore XML già gestisce.

Questo è il punto in cui XML è una scelta migliore di JSON rispetto ai formati tabellari. Convertire lo stesso array in CSV costringe a scegliere tra colonne extra, una stringa concatenata o righe extra, e ognuna di queste è sbagliata per qualcosa. In XML la ripetizione è nativa, e un ordine con cinque voci si converte senza che nessuna decisione venga presa al posto dell’utente.

XML ha due modi per legare un valore a un elemento — un attributo dentro al tag o un elemento figlio — e gli schemi tengono molto a quale dei due. JSON ne ha uno. La convenzione adottata qui colma il divario : una chiave che inizia con @ viene scritta come attributo, e una chiave chiamata #text fornisce il testo proprio dell’elemento accanto ai suoi figli.

Non è una convenzione arbitraria : è ciò che il lettore XML di questo sito produce nella direzione opposta. Un documento convertito in JSON, modificato e riconvertito restituisce gli attributi come attributi invece di promuoverli a elementi, ed è ciò che rende un passaggio attraverso JSON un modo utilizzabile per modificare un payload XML. Se l’intake si aspetta id come attributo e il JSON lo ha come chiave semplice, rinominare quella chiave in @id prima della conversione è l’intera correzione.

Le chiavi JSON possono essere qualsiasi stringa : spazi, barre, emoji, un numero iniziale, una stringa vuota. I nomi di elemento XML non possono. Il convertitore riscrive invece di fallire, e riscrive contro un elenco deliberatamente stretto — A-Z, a-z, 0-9, underscore, punto e trattino vengono mantenuti, tutto il resto diventa un underscore, e un nome che inizia con una cifra ne riceve uno davanti. Così "2024 report" arriva come <_2024_report>.

L’elenco è più stretto di quello di XML 1.0, e questo è il caso più probabile che coglie di sorpresa : i nomi di elemento XML possono contenere lettere accentate, greco, cirillico, devanagari e CJK, mentre questo convertitore non ne mantiene nessuno. Una chiave chiamata café arriva come <caf_> e 名前 arriva come <__>, quindi un payload le cui chiavi siano in qualcosa di diverso dall’ASCII perde i nomi invece dei valori. Il file è ben formato, ma i nomi non sono quelli che lo schema dichiara. Rinominare quelle chiavi nel JSON, o ristrutturare in modo che la parte variabile sia un valore invece di una chiave, è ciò che il lato XML avrebbe richiesto comunque.

XML porta con sé namespace, schemi XSD, DTD, istruzioni di elaborazione, sezioni CDATA e firme digitali — il registro indica il supporto delle firme come uno dei suoi tratti, ed è il motivo per cui il formato resta la spina dorsale dello scambio bancario e governativo. Nulla di tutto ciò può essere derivato da un file JSON, perché nulla di tutto ciò è espresso in un JSON.

In pratica questo significa : l’output è un documento ben formato, non un documento valido. Se l’intake valida contro un XSD, ci si aspetti di dover aggiungere una dichiarazione di namespace sull’elemento radice e possibilmente di riordinare gli elementi, perché la sequenza XSD è sensibile all’ordine mentre l’ordine delle proprietà in un oggetto JSON non è significativo. Entrambi sono interventi sull’output o su un piccolo passo XSLT, ed entrambi sono molto più rapidi una volta che il documento è in mano rispetto a quando sono teorici.

E commerciale, parentesi angolate e doppie virgolette in un valore vengono convertiti in escape in uscita, ed è ciò che impedisce a una descrizione prodotto che contiene «Tom & Jerry <special>» di terminare il documento in anticipo. Tutto il resto, inclusi gli apostrofi e ogni carattere non ASCII, passa inalterato come UTF-8.

Un null JSON diventa un elemento vuoto : il tag è presente senza nulla tra le due metà. È una scelta deliberata e non è l’unica disponibile — XML ha anche xsi :nil per questo, e alcuni schemi lo richiedono. Se è quello il vostro caso, gli elementi vuoti sono a una ricerca-e-sostituzione di distanza, e sapere quale dei due il consumatore si aspetta vale la pena verificarlo prima della prima consegna piuttosto che dopo.

Il documento è scritto con indentazione di due spazi e un elemento per riga, il che lo rende leggibile e rende leggibile un diff tra due payload. Non inizia con la riga < ?xml version="1.0" ?>. XML 1.0 rende la dichiarazione facoltativa e definisce UTF-8 come codifica predefinita, quindi il file è ben formato anche senza.

Un buon numero di sistemi più vecchi non sono d’accordo, e alcuni di essi falliscono con un messaggio poco utile quando la riga manca. È una riga da aggiungere in cima. Vale la pena saperlo prima di un primo invio, perché «il file non è valido» da una coda middleware dice raramente quale delle venti cose possibili intende.

Ogni valore è avvolto in un tag di apertura e in uno di chiusura, quindi i nomi di campo compaiono due volte per record invece di una. Per un payload di valori piccoli con nomi di campo lunghi il documento può essere da due a tre volte la dimensione del JSON da cui proviene, e l’indentazione si aggiunge a questo.

È un costo reale su una coda con un limite di dimensione del messaggio e nessun costo su un trasferimento di file, che è dove vanno in realtà la maggior parte di queste consegne. Dove conta, la risposta è la compressione piuttosto che la ristrutturazione — XML è testo altamente ripetitivo e si comprime estremamente bene, e la maggior parte degli intake che limitano la dimensione del messaggio accetta un payload compresso.

Due controlli, in ordine. Ben formato prima : qualsiasi editor XML, browser o parser da riga di comando dirà in un secondo se il documento viene parsato, e una conversione che ha prodotto qualcosa di non parsabile vale la pena saperlo prima di qualsiasi altra cosa. Qui dovrebbe sempre passare.

Validazione contro lo schema dopo, e ci si aspetti che fallisca la prima volta. I fallimenti sono informativi — un namespace mancante, un elemento nell’ordine sbagliato, un wrapper obbligatorio che il JSON non aveva motivo di includere — e ognuno è una piccola correzione nel JSON o nell’output. Farlo una volta produce un modello in cui convertire ogni payload successivo.

La conversione è JavaScript in questa scheda : il browser parsa il JSON, un piccolo scrittore produce l’XML, e nessuna richiesta porta il documento da qualche parte. Non c’è registrazione, coda o limite giornaliero, e il livello gratuito accetta fino a 100 MB.

Per questo pubblico è spesso il fattore decisivo più che un dettaglio. I payload che devono diventare XML sono pagamenti, reclami, dichiarazioni e cartelle cliniche o di clienti — le categorie esatte in cui incollare un file in un servizio web sconosciuto è un evento da segnalare. Qui nulla viene inviato, e quindi nulla da segnalare.