Convertir XML en NDJSON

Le NDJSON a besoin de quelque chose sur quoi se découper, et la découpe se fait ici sur une liste à l’extérieur des données analysées. L’analyse XML n’en produit jamais : le résultat est toujours un objet avec une seule clé, le nom de l’élément racine, contenant tout le reste. Une valeur en entrée, une ligne en sortie.

Cela vaut quelle que soit la taille du fichier et quel que soit le nombre d’éléments répétés qu’il contient. Un export de 40 Mo contenant dix mille enregistrements se convertit en une seule ligne de 40 Mo. Rien n’est perdu et rien n’est découpé, et si ce dont vous aviez besoin était dix mille lignes, cette conversion ne l’a pas fait.

La voie qui fonctionne est en deux étapes. Convertissez le fichier en JSON, puis passez-le dans jq : sélectionnez le chemin qui contient l’élément répété, itérez dessus, et utilisez l’option de sortie compacte pour que chaque objet atterrisse sur sa propre ligne. C’est une seule commande, c’est répétable dans un script, et cela met le choix de ce qui compte comme enregistrement là où il doit être — chez vous.

Aucun convertisseur ne peut faire ce choix depuis le document seul. Dans un flux RSS, l’enregistrement est l’élément item ; dans une réponse SOAP, c’est peut-être une ligne trois niveaux à l’intérieur du corps ; dans un export bancaire, c’est ce que le fournisseur a décidé d’appeler une transaction. Un outil qui devinerait aurait raison assez souvent pour être cru et faux assez souvent pour corrompre un chargement.

Cette paire n’est pas sans usage. Si vos entrées sont beaucoup de petits documents XML plutôt qu’un grand seul — un répertoire de factures, un dossier de manifestes, un lot de charges utiles par événement — alors une ligne par fichier est précisément la forme que veut un chargeur, et concaténer les sorties produit un flux NDJSON valide avec un enregistrement par document source.

Cela fonctionne aussi pour l’inventaire. Convertir chaque fichier de config d’un dépôt et ajouter les lignes à la suite vous donne un jeu de données requêtable de ce que ces fichiers contiennent, ce qui est une chose réellement utile à avoir et difficile à obtenir autrement. Dans les deux cas, la conversion fait son travail et la ligne unique est la fonctionnalité.

Même après avoir découpé les enregistrements, un comportement XML les suit. Un élément répété ne devient un tableau que lorsqu’il se répète : un enregistrement contenant un élément tag produit une chaîne, et un enregistrement en contenant deux produit une liste de chaînes. À l’intérieur d’un même export, certaines lignes auront le tableau et d’autres non.

Un magasin en schema-on-read inférera un type depuis les premiers enregistrements qu’il voit, puis rejettera ou contraindra les autres. La correction appartient au passage jq plutôt qu’au chargeur : normalisez en tableau chaque champ qui peut se répéter pendant que vous émettez chaque ligne, pour que le flux soit uniforme avant que quoi que ce soit en aval ne le voie.

Du JSON compact sans indentation, des clés dans l’ordre du document, terminé par un saut de ligne. Les attributs apparaissent comme des clés préfixées par @ et le texte d’un élément qui a aussi des attributs apparaît sous #text. Un préfixe d’espace de noms reste à l’intérieur du nom de clé, donc soap:Body est une clé avec deux-points dedans, et un document avec une déclaration XML porte une clé de premier niveau supplémentaire nommée ?xml.

Ces deux derniers méritent d’être retirés avant un chargement. Des noms de champ contenant des deux-points et des points d’interrogation sont maladroits ou invalides dans bon nombre de moteurs de requête et de schémas de table, et la déclaration est une métadonnée sur le fichier plutôt qu’une donnée du fichier.

Les valeurs d’apparence numérique sont analysées, dans les attributs comme dans le texte des éléments. C’est commode pour un compte et destructeur pour des identifiants : une référence de commande écrite 007 arrive en tant que nombre 7, et un attribut version écrit 1.0 arrive en 1. Dans un entrepôt de données, ces valeurs deviennent des colonnes numériques et le remplissage initial a disparu de chaque ligne.

Un cas se comporte mieux qu’on ne le craindrait : un entier trop long pour survivre comme nombre JSON est laissé comme chaîne plutôt qu’arrondi, donc une référence à dix-neuf chiffres arrive intacte. La notation scientifique n’a pas cette protection — une valeur écrite 1e3 arrive comme 1000. Rien ne déclenche d’erreur dans les deux cas. Si l’export contient des numéros de référence sur lesquels vous ferez des jointures plus tard, reconvertissez-les en chaînes dans le passage jq, avant le premier chargement plutôt qu’après.

NDJSON est lu directement par jq, par pandas avec son option lines, et comme format de chargement par les chargeurs d’entrepôts courants. Elasticsearch en bloc a besoin d’une ligne d’action avant chaque document, ce qui s’ajoute dans le même passage jq qui découpe les enregistrements.

Ce qu’il faut prévoir avec cette paire spécifiquement est la longueur de ligne. Un lecteur qui traite une ligne à la fois doit garder cette ligne entière en mémoire, donc une ligne de document entier est un tampon de document entier, et toute limite de taille par enregistrement dans la destination s’applique au fichier complet plutôt qu’à un enregistrement. C’est la raison pratique de découper les enregistrements avant le chargement plutôt qu’après.

Si l’export est gros, arrive régulièrement et doit devenir un flux à chaque fois, la recommandation honnête n’est pas du tout un convertisseur de navigateur. Un analyseur en flux lit un fichier XML élément par élément sans construire l’arbre entier en mémoire, et émettre une ligne JSON par enregistrement depuis cette boucle est un programme court dans n’importe quel langage.

Cette approche survit aussi aux fichiers plus grands que la mémoire, ce que rien sur cette page ne fait — l’analyse ici construit le document entier comme objets JavaScript avant qu’un seul octet ne soit écrit. Pour un fichier ponctuel, ou pour les cas par fichier ci-dessus, le convertisseur est plus rapide que d’écrire le programme. Pour un pipeline récurrent, il ne l’est pas.

Les commentaires XML sont supprimés pendant l’analyse et NDJSON n’a pas de syntaxe de commentaires pour les recevoir, donc toute documentation à l’intérieur de l’export a disparu. Il n’y a pas non plus d’en-tête, pas de schéma et pas de préambule : chaque ligne d’un fichier NDJSON est un enregistrement, et un chargeur essaiera de lire tout ce qui se trouve en haut du fichier comme tel.

Si le chargement a besoin d’enregistrer d’où viennent les données, cela appartient à un champ de l’enregistrement ou au nom de fichier. L’ajouter comme première ligne rend le fichier invalide pour son propos, et le chargeur vous le dira d’une manière bien moins claire que ce paragraphe.