Convertire XML in JSON

XML porta informazione in tre posti — nomi degli elementi, attributi e testo — e JSON ha solo chiavi e valori, quindi serve una convenzione. Questa è quella comune: ogni elemento diventa una chiave il cui valore è un oggetto con i suoi figli, ogni attributo diventa una chiave su quello stesso oggetto preceduta da @, e il testo proprio di un elemento, quando ha figli o attributi accanto, viene memorizzato sotto la chiave #text.

Un elemento con solo testo è più semplice: diventa una stringa senza alcun oggetto contenitore. Questa incoerenza è inevitabile e conviene interiorizzarla presto, perché significa che il valore a un certo percorso è a volte una stringa e a volte un oggetto, a seconda che l’elemento sorgente avesse per caso un attributo.

Questo è l’aspetto più costoso nel consumare XML convertito. Un documento XML non dice quali elementi si ripetono — solo uno schema lo direbbe, e il parser non ne sta leggendo uno. Quindi un canale con un solo elemento item produce un oggetto, e un canale con due produce un array di oggetti.

Codice scritto contro un feed RSS completo si rompe il giorno in cui il feed ha una sola voce, e codice scritto contro una risposta SOAP con un solo record si rompe la prima volta che ne arrivano due. Non c’è opzione qui che lo risolva, perché servirebbe conoscere lo schema. Scrivete il consumer per accettare entrambe le forme: convertite ogni collezione in array come prima cosa, prima che qualsiasi altra logica la tocchi.

Una busta SOAP arriva con i prefissi intatti: soap:Envelope diventa una chiave chiamata letteralmente "soap:Envelope", e le dichiarazioni di namespace arrivano come attributi tipo "@xmlns:soap". Niente viene risolto, niente viene rimosso.

È fedele ed è fragile, perché un prefisso è arbitrario. Un servizio che emette soapenv:Envelope una settimana e soap:Envelope quella dopo ha prodotto due documenti equivalenti e due strutture JSON incompatibili. Se controllate il consumer, confrontate il nome locale dopo i due punti invece della chiave completa, e non codificate mai un prefisso che non avete definito voi.

Un documento che apre con una dichiarazione di versione e codifica produce una chiave di primo livello chiamata "?xml" con i suoi attributi, accanto alla chiave dell’elemento radice. Non fa parte del contenuto del documento, ma è nel vostro JSON.

Gestitela ignorandola o eliminandola, ma non assumete che l’elemento radice sia l’unica chiave di primo livello. Codice che legge la prima chiave dell’oggetto per trovare la radice troverà invece la dichiarazione su qualsiasi documento che ne ha una, cioè sulla maggior parte.

I valori che sembrano numerici diventano numeri JSON, sia negli attributi sia nel testo degli elementi. Un attributo version scritto 1.0 diventa 1. Un identificativo scritto 007 diventa 7. Un valore con zeri iniziali scritto 0755 diventa 755.

È comodo per un conteggio e distruttivo per qualsiasi cosa trattaste come token opaco. Numeri d’ordine, codici prodotto, codici postali, versioni di protocollo e permessi file falliscono tutti allo stesso modo, e nessuno solleva un errore. Conviene controllare, una volta, ogni attributo dell’output che intendete confrontare come stringa.

I commenti vengono eliminati senza traccia, il che su un payload è di solito innocuo e su un file di configurazione è una perdita reale. CDATA viene srotolato: qualunque cosa fosse dentro la sezione diventa una stringa ordinaria, quindi un frammento HTML avvolto in CDATA — il modo normale in cui un feed RSS trasporta il corpo di un articolo — arriva come testo con parentesi angolari, e convertirlo di nuovo in XML le sfuggirebbe invece di ricostruire la sezione CDATA.

Il contenuto misto è il caso senza buona soluzione. Un elemento che contiene testo, poi un elemento figlio, poi altro testo tiene il figlio sotto la propria chiave e concatena le due porzioni di testo in un unico valore #text, senza alcun marcatore di dove il figlio si trovasse in mezzo. Qualsiasi documento dove prosa e markup si intrecciano — XHTML, DocBook, qualunque cosa narrativa — perde qui il proprio ordine.

Un elemento autochiudente e un elemento con corpo vuoto diventano entrambi una stringa vuota. XML non fa distinzione fra i due neppure lui, quindi nulla è stato perso, ma JSON ha null disponibile e non viene usato — un elemento vuoto è "" e non null.

La distinzione che invece sparisce è fra un elemento assente e uno presente ma vuoto, una volta che il vostro codice applica un valore predefinito. Entrambi finiscono per essere falsy. Dove la differenza conta — un campo opzionale esplicitamente svuotato contro uno mai impostato — controllate la presenza della chiave piuttosto che il suo valore.

Messa insieme, una risposta SOAP si legge come chiavi annidate: la chiave envelope, dentro la chiave body, poi la risposta dell’operazione, poi il payload. Ogni livello mantiene il proprio prefisso e il tutto è profondo tre o quattro oggetti prima che compaiano i vostri dati, esattamente come era verboso l’XML e più facile da percorrere da codice.

Un fault è il caso da testare per primo. I fault SOAP usano una struttura di elementi diversa da una risposta riuscita, quindi il JSON per un errore non somiglia affatto al JSON per un risultato, e un client che ha visto solo il percorso felice leggerà undefined su un percorso che non esiste più. Convertite qui una vera risposta di fault e scrivete il ramo d’errore contro di essa prima che vi serva.

L’output è indentato di due spazi, quindi si legge bene in revisione e si incolla direttamente in una fixture di test. Le fixture sono l’uso giusto per questo: convertire una risposta reale e archiviarla nel repository dà al consumer qualcosa di onesto contro cui essere testato, comprese tutte le stranezze descritte sopra.

Tre abitudini difensive coprono quasi ogni problema di questa pagina. Normalizzate in array tutto ciò che può ripetersi. Confrontate gli identificativi come stringhe, riconvertendoli in stringa al confine se il parser li ha resi numeri. Fate corrispondere le chiavi con namespace sulla loro parte locale.