Convertire XML in NDJSON

NDJSON ha bisogno di qualcosa su cui dividersi, e la divisione qui avviene su una lista all'esterno dei dati analizzati. Analizzare XML non ne produce mai una: il risultato è sempre un oggetto con una sola chiave, il nome dell'elemento radice, che contiene tutto il resto. Un valore in ingresso, una riga in uscita.

Vale a prescindere da quanto sia grande il file e da quanti elementi ripetuti contenga. Un'esportazione da 40 MB di diecimila record converte in una singola riga da 40 MB. Nulla si perde e nulla si divide, e se servivano diecimila righe, questa conversione non lo ha fatto.

La via che funziona sono due passi. Si converte il file in JSON, poi lo si esegue attraverso jq: si seleziona il percorso che contiene l'elemento ripetuto, lo si itera, e si usa il flag di output compatto così che ogni oggetto atterri sulla propria riga. È un comando, è ripetibile in uno script, e mette la scelta di cosa conti come record dove appartiene — a chi lo fa.

Nessun convertitore può fare quella scelta dal solo documento. In un feed RSS il record è l'elemento item; in una risposta SOAP potrebbe essere una riga tre livelli dentro il body; in un'esportazione bancaria è qualunque cosa il fornitore abbia deciso di chiamare transazione. Uno strumento che indovinasse sarebbe giusto abbastanza spesso da essere considerato affidabile e sbagliato abbastanza spesso da corrompere un caricamento.

Non è una coppia senza uso. Se i propri input sono molti piccoli documenti XML invece di uno grande — una directory di fatture, una cartella di manifesti, un lotto di payload per evento — allora una riga per file è precisamente la forma che vuole un caricatore, e concatenare gli output produce uno stream NDJSON valido con un record per documento sorgente.

Funziona anche per l'inventario. Convertire ogni file config in un repository e aggiungere le righe dà un dataset interrogabile di cosa contengono quei file, una cosa genuinamente utile da avere e difficile da ottenere altrimenti. In entrambi i casi la conversione sta facendo il suo lavoro e la singola riga è la funzione.

Anche dopo aver diviso i record, un comportamento XML li segue. Un elemento ripetuto diventa un array solo quando si ripete: un record che contiene un elemento tag produce una stringa, e un record che ne contiene due produce una lista di stringhe. Dentro una singola esportazione, alcune righe avranno l'array e altre no.

Un archivio schema-on-read dedurrà un tipo dai primi record che vede e poi rifiuterà o coercirà il resto. Il rimedio appartiene al passaggio jq piuttosto che al caricatore: si normalizza ogni campo che può ripetersi in un array mentre si emette ogni riga, così lo stream è uniforme prima che qualcosa a valle lo veda.

JSON compatto senza indentazione, chiavi nell'ordine del documento, terminato da un a capo. Gli attributi appaiono come chiavi prefissate con @ e il testo dell'elemento su un tag che ha anche attributi appare sotto #text. Un prefisso namespace resta dentro il nome della chiave, quindi soap:Body è una chiave con i due punti dentro, e un documento con una dichiarazione XML porta una chiave extra di primo livello chiamata ?xml.

Queste ultime due valgono la pena rimuoverle prima di un caricamento. Nomi di campo con due punti e punti interrogativi sono scomodi o non validi in un buon numero di motori di query e schemi tabella, e la dichiarazione è metadato sul file piuttosto che dato da esso.

I valori dall'aspetto numerico vengono analizzati, sia negli attributi sia nel testo degli elementi. È comodo per un conteggio e distruttivo per gli identificatori: un riferimento d'ordine scritto 007 arriva come il numero 7, e un attributo di versione scritto 1.0 arriva come 1. In un data store diventano colonne numeriche e il riempimento sparisce da ogni riga.

Un caso si comporta meglio di quanto si potrebbe temere: un intero troppo lungo per sopravvivere come numero JSON viene lasciato come stringa invece che arrotondato, quindi un riferimento a diciannove cifre passa intatto. La notazione scientifica non ha quella protezione — un valore scritto 1e3 arriva come 1000. Nessun errore viene sollevato in nessuno dei due casi. Se l'esportazione contiene numeri di riferimento su cui si farà una join in seguito, li si riconverte in stringhe nel passaggio jq, prima del primo caricamento invece che dopo.

NDJSON viene letto direttamente da jq, da pandas con la sua opzione lines, e come formato di caricamento dai comuni caricatori di data warehouse. Il bulk di Elasticsearch richiede una riga azione prima di ogni documento, aggiunta nello stesso passaggio jq che divide i record.

La cosa da pianificare con questa coppia specificamente è la lunghezza di riga. Un lettore che elabora una riga alla volta deve tenere l'intera riga in memoria, quindi una riga a documento intero è un buffer a documento intero, e qualsiasi limite di dimensione per record nella destinazione si applica al file completo piuttosto che a un record. È il motivo pratico per dividere i record prima di caricare invece che dopo.

Se l'esportazione è grande, arriva regolarmente, e deve diventare uno stream ogni volta, il consiglio onesto non è affatto un convertitore browser. Un parser in streaming legge un file XML elemento per elemento senza costruire l'intero albero in memoria, ed emettere una riga JSON per record da quel ciclo è un programma breve in qualsiasi linguaggio.

Quell'approccio sopravvive anche a file più grandi della memoria, cosa che nulla su questa pagina fa — l'analisi qui costruisce l'intero documento come oggetti JavaScript prima che un solo byte venga scritto. Per un file una tantum, o per i casi per-file sopra, il convertitore è più veloce che scrivere il programma. Per una pipeline ricorrente no.

I commenti XML vengono scartati durante l'analisi e NDJSON non ha sintassi commenti per riceverli, quindi qualsiasi documentazione dentro l'esportazione sparisce. Non c'è nemmeno intestazione, schema o preambolo: ogni riga in un file NDJSON è un record, e un caricatore proverà a leggere qualsiasi cosa in cima al file come tale.

Se il caricamento deve registrare da dove vengono i dati, appartiene a un campo sul record o al nome del file. Aggiungerlo come prima riga rende il file non valido per il suo scopo, e il caricatore lo dirà in un modo molto meno chiaro di questo paragrafo.