JSON Lines : une valeur par ligne pour les journaux, les jeux de données et les réponses en flux

Ce que c'est

Le site JSON Lines (cité) énonce trois exigences : un encodage UTF-8 sans marque d'ordre des octets ; chaque ligne est une valeur JSON valide, si bien qu'une ligne vide est une erreur ; et le terminateur de ligne est \n (CRLF est toléré car les espaces blancs environnants sont ignorés lors de l'analyse d'une valeur). Un terminateur après la dernière valeur est recommandé afin que les fichiers se concatènent proprement. Les conventions sont l'extension .jsonl, gzip ou bzip2 pour la compression, et un type de média application/jsonl qui n'est pas encore normalisé. L'équivalent IETF, les séquences de texte JSON (RFC 7464, citée), place l'octet séparateur d'enregistrement ASCII (0x1E) avant chaque texte et enregistre application/json-seq ; ses règles d'analyse sont écrites de sorte qu'un élément tronqué puisse être sauté et le reste de la séquence récupéré, et elle ne comporte aucun marqueur de fin de séquence.

Pourquoi c'est important

Un tableau JSON est une seule valeur : le lecteur doit soit conserver le texte entier, soit utiliser un analyseur incrémental, et un tableau tronqué est tout simplement invalide. Avec une valeur par ligne, chaque enregistrement est analysé indépendamment, si bien qu'un rédacteur peut ajouter des données sans réécrire le fichier, une panne ne coûte au plus que la dernière ligne, un gros fichier peut être découpé par ligne pour un traitement parallèle, et les outils shell (grep, head, wc -l, jq -c) fonctionnent directement. Cette même propriété rend le format adapté aux réponses HTTP en flux et aux messages entre processus.

Comment l'appliquer

• Sérialiser les enregistrements de façon compacte, jamais mis en forme pour la lecture : JSON échappe les caractères de contrôle à l'intérieur des chaînes, si bien qu'une valeur compacte ne contient aucun saut de ligne brut.
• Donner à chaque ligne la même forme (un objet avec des clés stables) et versionner cette forme dans le nom de fichier ou dans un enregistrement d'en-tête initial lorsqu'elle doit changer.
• Pour une réponse en flux, vider le tampon après chaque ligne, et placer un échec dans une ligne finale avec un membre "error" explicite ; le client ne peut pas se fier à un crochet fermant pour savoir si le flux s'est terminé proprement, il faut donc ajouter un enregistrement de fin explicite lorsque l'exhaustivité compte.
• Choisir application/json-seq lorsque le consommateur doit se remettre d'une corruption survenue au milieu d'un flux ; choisir JSON Lines lorsque la compatibilité avec les outils texte importe davantage.
• Compresser des fichiers entiers avec un compresseur de flux ; le format reste adressable ligne par ligne après décompression.

Pièges

Une seule ligne très longue doit tout de même tenir en mémoire. Les outils qui découpent sur un CR isolé ou sur U+2028 s'écartent de la spécification. Compter « ligne 1 » dans un éditeur et « valeur 1 » dans un programme (le site suggère cette dernière convention) donne des rapports d'erreur décalés d'une unité. Valider le fichier entier comme un seul document JSON échoue par construction ; valider ligne par ligne, et traiter une dernière ligne partielle comme une troncature plutôt que comme une corruption.