Convertir NDJSON en YAML

YAML a été pensé pour des fichiers de configuration, où un document complet est la norme et où l’ordre des clés n’a pas d’importance. Un NDJSON est un flux, où l’ordre des lignes est l’ordre temporel des événements et où chaque ligne est un document. La conversion doit prendre une décision de représentation, et la plus naturelle est d’écrire chaque enregistrement comme un document YAML séparé dans le même fichier.

Le résultat est un fichier qui contient une suite de documents séparés par `---`, ce qui est la forme multi-document standard de YAML. Un parseur qui supporte les flux multi-documents les lira tous, un parseur qui ne supporte que le premier s’arrêtera au premier. Pour un export à destination d’un humain qui lit dans un éditeur, c’est très lisible ; pour un export à destination d’une configuration, c’est probablement pas la bonne cible.

Les lignes du NDJSON sont lues dans l’ordre du fichier et écrites dans le même ordre, avec la marque `---` entre chaque document. L’ordre d’un journal n’est pas un détail : c’est ce qui rend lisible une trace d’activité, et c’est souvent la seule information qui permet de reconstruire une chronologie d’incident.

La conversion n’échange pas l’ordre, ne le déduplique pas, et ne le retrie pas. Si deux lignes sont identiques, deux documents identiques sont écrits, parce que c’est ce que le fichier dit. Le tri, s’il est nécessaire, est une étape séparée, et c’est à l’outil qui l’applique de dire sur quel critère il le fait.

Un nombre en NDJSON arrive en nombre dans le YAML, sans guillemet, ce qui le rend lisible et typé à la lecture. Une chaîne qui ressemble à un nombre — un identifiant, un code postal — est protégée par des guillemets ou une apostrophe quand la conversion détecte l’ambiguïté, parce qu’un YAML qui transforme un identifiant postal en nombre est un YAML qui a perdu une information.

Cette protection suit des règles précises : ce qui commence par un chiffre et ne contient que des chiffres est traité comme un nombre si le contexte ne dit pas autre chose, et ce qui contient autre chose est traité comme une chaîne. La sortie est rarement ambiguë, et un coup d’œil dans l’éditeur lève les doutes sur les cas limites.

YAML représente les structures imbriquées par indentation, sans accolade ni crochet. Un objet `request` avec une méthode et un chemin en NDJSON arrive en YAML avec les deux clés sous `request:`, indentées de deux espaces. La structure est plus lisible qu’un CSV ou un TSV, parce qu’elle montre la hiérarchie au lieu de l’aplatir.

C’est l’intérêt principal de cette conversion pour des configurations. Un export de base de données qui produit des lignes imbriquées devient un YAML lisible par un humain, et un fichier de configuration peut être chargé en quelques lignes dans la plupart des langages. Pour un journal de logs, l’intérêt est plus mince, parce que les fichiers de logs sont rarement chargés comme configuration, et l’imbrication ajoute des lignes sans ajouter d’analyse.

YAML permet de définir une ancre `&nom` et d’y faire référence par `*nom` plus loin dans le document. C’est un mécanisme de factorisation qui réduit la duplication dans les fichiers de configuration. La conversion ne le reconstruit pas, parce que la factorisation n’a pas de représentation en JSON, et un aller-retour YAML → NDJSON → YAML ne donnera pas un fichier factorisé.

Pour un fichier qui n’utilisait pas d’ancres — la grande majorité des YAML de configuration — la conversion est sans perte. Pour un fichier qui en utilisait, le résultat est équivalent en contenu mais pas en taille, et c’est une limite de la conversion, pas un défaut à corriger.

Si une ligne n’est pas un JSON valide, la conversion ne continue pas au-delà. Le message dit laquelle : « Ce fichier n’a pas pu être lu comme NDJSON — la ligne 3 n’est pas un JSON valide. » C’est le même comportement que pour les autres cibles de cette catégorie, et la raison est la même : sauter la ligne en silence produirait un fichier auquel manquerait un nombre inconnu d’enregistrements sans rien pour l’indiquer.

Le numéro de ligne en main, supprimer ou réparer la queue prend une seule commande, et la personne qui nettoie sait exactement ce qu’elle a perdu. Pour un export de base de données, l’erreur est en général dans la dernière ligne, parce que c’est elle qui a été tronquée par une rotation de table ou un timeout d’export.

La conversion lit le NDJSON dans l’onglet et écrit le YAML dans l’onglet. Aucune requête ne porte le fichier, et l’onglet réseau est vide pendant l’opération. Pour un export applicatif qui contient des chemins, des identifiants d’utilisateur, des fragments de configuration — un dump d’incident, un export de base interne — c’est la forme de conversion qui ne crée pas de copie sur l’infrastructure d’un tiers.

La taille maximale acceptée par la version gratuite est 100 Mo par fichier. Un export de production dépasse cela en général, et le découpage se fait avant la conversion, soit par date soit par service, avec un outil local. La conversion ne fait pas ce travail, parce qu’elle n’a pas le contexte pour décider ce qu’il faut garder et ce qu’il faut jeter.

YAML permet de définir une ancre `&nom` et d’y faire référence par `*nom` plus loin dans le document. C’est un mécanisme de factorisation qui réduit la duplication dans les fichiers de configuration, et un export de base de données qui produit des structures répétitives pourrait en bénéficier. La conversion ne le reconstruit pas, parce que la factorisation n’a pas de représentation en JSON, et un aller-retour YAML → NDJSON → YAML ne donnera pas un fichier factorisé.

Pour un fichier qui n’utilisait pas d’ancres — la grande majorité des YAML de configuration — la conversion est sans perte. Pour un fichier qui en utilisait, le résultat est équivalent en contenu mais pas en taille, et c’est une limite de la conversion, pas un défaut à corriger. Si la cible attend un YAML factorisé, passer par un outil qui ré-ancre après export est la voie normale, et c’est ce que fait un script de post-traitement de quelques lignes.

YAML accepte des commentaires avec le caractère `#`, et un fichier de configuration typique en est rempli pour expliquer la signification d’une clé. Le JSON qui est la source de cette conversion ne porte pas de commentaires, et la conversion ne peut pas en inventer. La sortie est un YAML strict, sans annotation humaine, et c’est cohérent avec ce que contient un NDJSON en général.

Pour un fichier de configuration destiné à être lu par un humain, les commentaires sont perdus, et c’est un point à savoir. Ajouter les commentaires après la conversion, dans l’ordre où le YAML les aurait eus, est la voie normale. Pour un fichier destiné à être chargé par une machine, l’absence de commentaires est sans conséquence, parce que la machine les ignorerait.