XML naar NDJSON omzetten

Newline-delimited JSON heeft iets nodig om op te splitsen, en die splitsing gebeurt hier bij een lijst buitenaan de geparste data. XML parsen levert die nooit op: het resultaat is altijd een object met één sleutel, de naam van het root-element, met alles daaronder erin.

Dat geldt hoe groot het bestand ook is en hoeveel herhaalde elementen het bevat. Een export van 40 MB met tienduizend records wordt één regel van 40 MB. Niets gaat verloren en niets wordt gesplitst — was het jouw doel tienduizend regels, dan heeft deze omzetting dat niet gedaan.

De route die werkt is twee stappen: zet het bestand eerst om naar JSON, en gebruik dan jq om het pad met het herhaalde element te selecteren, te doorlopen en compact per regel weg te schrijven. Het is één commando, herhaalbaar in een script.

Geen converter kan die keuze zelf maken uit het document alleen. In een RSS-feed is het record het item-element; in een bankexport is het wat de leverancier een transactie noemt. Een tool die zou gokken zou vaak genoeg juist zijn om vertrouwd te worden en vaak genoeg fout om een lading te beschadigen.

Dit paar heeft wel degelijk een goed gebruik. Zijn de invoerbestanden veel kleine XML-documenten in plaats van één groot bestand — een map facturen, een reeks handleveranciersbestanden — dan is één regel per bestand precies de vorm die een lader wil.

Het werkt ook voor inventarisatie: elk configuratiebestand in een repository omzetten en de regels aan elkaar plakken levert een bevraagbare dataset op. In beide gevallen doet de omzetting zijn werk en is de ene regel het kenmerk, niet het probleem.

Ook na het splitsen volgt één XML-gedrag mee. Een herhaald element wordt alleen een array als het herhaalt: een record met één tag-element levert een string op, met twee een lijst van strings. Binnen één export hebben sommige regels de array en andere niet.

De oplossing hoort in de jq-stap: normaliseer elk veld dat kan herhalen naar een array bij het wegschrijven van elke regel, zodat de stream uniform is voordat er iets stroomafwaarts naar kijkt.

Compacte JSON zonder inspringing, sleutels in documentvolgorde, afgesloten met een newline. Attributen verschijnen als sleutels met een @ ervoor, en elementtekst op een tag met attributen komt onder een sleutel #text.

Een naamruimtevoorvoegsel blijft in de sleutelnaam staan, dus soap:Body is een sleutel met een dubbele punt erin, en een document met een XML-declaratie krijgt een extra sleutel ?xml. Beide zijn het waard om vóór een lading te verwijderen.

Waarden die er numeriek uitzien worden geparst, zowel in attributen als elementtekst. Handig voor een aantal, vervelend voor identificatoren: een ordernummer geschreven als 007 komt binnen als het getal 7, en een versieattribuut geschreven als 1.0 als 1.

Eén geval gaat goed: een geheel getal te lang om als JSON-getal te overleven, blijft een string in plaats van afgerond te worden. Wetenschappelijke notatie krijgt die bescherming niet — 1e3 komt binnen als 1000.

NDJSON wordt rechtstreeks gelezen door jq, door pandas met zijn lines-optie, en als laadformaat door de gangbare warehouse-laders. Elasticsearch bulk heeft een actieregel vóór elk document nodig, toe te voegen in dezelfde jq-stap die de records splitst.

Wat bij dit paar specifiek aandacht verdient is de regellengte. Een lezer die regel voor regel verwerkt, moet die hele regel in het geheugen houden — een hele-documentregel is dus een hele-documentbuffer.

Is de export groot, komt hij regelmatig binnen en moet hij telkens een stream worden, dan is het eerlijke advies geen browserconverter. Een streaming parser leest een XML-bestand element voor element zonder de hele boom in het geheugen te bouwen.

Dat overleeft ook bestanden groter dan het geheugen, wat niets op deze pagina doet — hier wordt het hele document eerst als JavaScript-objecten opgebouwd. Voor een eenmalig bestand is de converter sneller; voor een terugkerende pijplijn niet.

XML-commentaar wordt tijdens het parsen weggegooid en NDJSON heeft geen commentaarsyntax om het te ontvangen, dus documentatie in de export is verdwenen. Er is ook geen kopregel, geen schema en geen voorwoord: elke regel in een NDJSON-bestand is een record.

Moet de lading weten waar de data vandaan kwam, zet dat dan in een veld op het record of in de bestandsnaam. Het als eerste regel toevoegen maakt het bestand ongeldig voor zijn doel.