Convertir YAML en NDJSON

Toute la conversion tient dans cette distinction. NDJSON est JSON Lines : un fichier où chaque ligne est un objet JSON valide, terminée par un saut de ligne, et où le fichier entier est lu ligne par ligne. Cela permet à un consommateur de traiter un enregistrement à la fois sans charger le reste, ce qui est la propriété qui rend le format irremplaçable pour les journaux, les flux d’événements et les gros exports.

YAML est une structure en arbre, et la conversion doit décider ce que devient cet arbre quand il doit devenir un flux. La règle qu’applique ce convertisseur est : un document YAML qui est une séquence au plus haut niveau produit une ligne par élément ; un document qui est un mapping au plus haut niveau produit une seule ligne. Les deux sont des usages réels, et le reste de la page dépend de cette distinction.

Un fichier qui commence par un tiret est une liste, et chaque élément devient une ligne du NDJSON. Un manifeste Kubernetes avec trois ressources, un export de base de données de cent lignes, un journal de cinquante requêtes, donnent cinquante ou cent lignes de NDJSON, et chaque ligne est un objet JSON indépendant qui peut être parsé sans connaître les autres.

C’est la conversion la plus utile, et c’est aussi celle qui rend le résultat lisible dans un pager ou dans jq. jq -c . < fichier.ndjson opère sur chaque ligne en isolation, et un script qui consomme l’export peut commencer à travailler avant que la source entière soit chargée. Pour les outils de streaming comme les connecteurs Kafka, c’est la forme qui convient.

Un fichier qui commence par une clé-valeur sans tiret est un objet, et la conversion produit une seule ligne : le mapping complet sérialisé en JSON. Le résultat est syntaxiquement NDJSON valide, et c’est la conversion triviale qu’un script de journal ferait d’une configuration chargée une fois au démarrage.

C’est aussi le cas où la conversion est presque toujours la mauvaise réponse. Un objet unique tient plus naturellement dans un fichier JSON classique, et le mettre en NDJSON sans raison force le consommateur à traiter une ligne qu’il ne sait pas gérer comme un flux. Si votre YAML est un mapping, le bon outil est yaml-to-json, pas celui-ci.

YAML admet plusieurs documents séparés par trois tirets. La conversion sort le premier et ignore les suivants, en avertissant. Pour un bundle Kubernetes concaténé, cela veut dire perdre la moitié des ressources, ce qui est presque toujours un bogue et jamais ce que l’auteur voulait.

La correction est de séparer le fichier multi-document en fichiers à un document, puis de convertir chacun. Un script de deux lignes avec un split sur la ligne « --- » fait le travail, et l’ordre des ressources est préservé. C’est aussi le moment de vérifier que le résultat est bien la liste aplatie que le consommateur en aval attendait — un bundle Kubernetes est en général un mapping avec une clé items, et la conversion donne une ligne qui contient ce mapping complet, pas une ligne par resource.

YAML 1.2 distingue null, bool, int, float et string, et la conversion émet true, false, null, les nombres et les chaînes de la même manière qu’un sérialiseur JSON standard. Le NDJSON hérite donc des types du YAML, et un consommateur qui vérifie la présence d’une clé n’a pas à s’inquiéter de la forme textuelle d’une valeur booléenne.

Le cas « 1.0 » reste une chaîne, comme dans YAML. Le cas « 2024-01-01 » reste une chaîne, parce que YAML 1.2 ne l’interprète plus comme un horodatage. Pour un export de base, c’est correct : un consumer Python qui lit line[« date »] reçoit une chaîne et la convertit avec datetime.fromisoformat s’il veut un objet date. Aucune conversion silencieuse qui changerait le type de la valeur.

Un bloc partagé dans YAML est référencé par alias dans la source, et la conversion le développe en une copie complète pour chaque référence. Le résultat est correct et plus volumineux : un export de cent lignes où chaque ligne partage la même configuration pèse cinq fois plus que la source si la même configuration apparaît à cinq endroits.

Pour un export, c’est indolore. Pour un fichier de configuration converti par erreur en NDJSON, c’est une surprise : la compression gzip en aval ne récupère pas toute la duplication, parce qu’elle est à l’intérieur d’une même ligne. Si la taille compte, déplier les ancres à la main en YAML avant la conversion est l’édition qui vaut la peine.

Un scalaire bloc YAML avec un pipe représente une chaîne sur plusieurs lignes. Le NDJSON n’a pas de représentation multi-ligne : une ligne est une ligne, terminée par un saut de ligne. La conversion joint les lignes en une seule, avec un espace entre elles, ce qui est ce que la plupart des consommateurs NDJSON attendent d’une chaîne multi-ligne collapsée.

Cette perte est parfois souhaitée et parfois pas. Un manifeste Kubernetes avec un script shell embarqué perd la lisibilité du bloc, et NDJSON résultant est une longue ligne que personne ne va relire. Pour ce cas, garder YAML comme source et ne pas le convertir est la bonne réponse. Pour un export de données, la perte est acceptable parce que la cible ne lira pas la chaîne en isolation.

YAML autorise un commentaire n’importe où sur une ligne, après un dièse. Le JSON n’a aucune production grammaticale pour un commentaire, et NDJSON non plus. La conversion les supprime sans trace, ce qui est la seule perte qui ne soit pas structurelle.

C’est cohérent avec ce que les outils en aval attendent : un pipeline qui lit du NDJSON ne sait pas quoi faire d’un commentaire, et un fichier qui en contiendrait serait silencieusement mal parsé. Si un commentaire est important, sa place est dans un fichier à côté du NDJSON, sous la forme d’une note de version ou d’un ticket lié à l’export.

jq -c . opère ligne par ligne sans charger le fichier en mémoire, et c’est l’outil de référence pour explorer un export NDJSON. Pour un fichier d’un gigaoctet, jq traite la première ligne en quelques millisecondes, ce qui rend possible l’inspection d’un export qui ne tiendrait pas en RAM en mode JSON classique.

Python et Node traitent NDJSON de la même manière, par lecture ligne par ligne et json.loads par ligne. C’est la propriété qui rend le format utile pour le streaming : un consommateur peut commencer à travailler sur l’enregistrement N avant que l’enregistrement N+1 soit arrivé. Aucune de ces propriétés n’est vraie d’un fichier JSON monolithique, et c’est la raison pour laquelle cette conversion existe.

C’est du JavaScript dans votre onglet. Le YAML est analysé par un parseur chargé à la demande, NDJSON est écrit par la même logique de sérialisation, et aucune requête ne porte le document. Il n’y a pas d’inscription, pas de file d’attente, et le niveau gratuit accepte jusqu’à 100 Mo.

Pour ce lectorat, c’est une préoccupation pratique plutôt qu’abstraite. Un export de base contient des identifiants et parfois des données personnelles, et un certain nombre d’organisations traitent le fait de coller cela dans un convertisseur web public comme un incident. Ici il n’y a rien à coller et rien à envoyer, et le code du parseur tourne dans l’onglet.