← Blog
Un dévidoir lavande avec un rouleau crème et un bord orange sur fond clair.
Publié le
2026-11-16

JSONL ou JSON : choisir le format de vos pipelines

Choisissez JSON lorsque le système destinataire attend un document complet, par exemple un objet de configuration ou une réponse d’API. Choisissez JSONL lorsqu’il attend une suite de valeurs lisibles indépendamment, comme les enregistrements d’un traitement. La différence porte sur la séparation des données, pas sur la possibilité de contenir des objets imbriqués.

Ce guide compare les deux formats et propose un lecteur et un générateur Python avec des limites d’entrée et une gestion des erreurs explicites. L’exemple utilise six valeurs synthétiques et a passé 16 tests locaux sous Windows avec CPython 3.12.14. Il ne mesure pas le débit et ne teste aucune intégration cloud.

JSONL ou JSON : les différences pratiques

DécisionDocument JSONFichier JSONL
Unité à lireUne valeur complète, souvent un objet ou un tableauUne valeur distincte par ligne
Contrat destinataire courantCorps de requête API, configuration ou export completImport d’enregistrements, lecture de journaux ou traitement
Conception du lecteurAnalyser le document, avec une lecture progressive si nécessaireLire et traiter les lignes successives
Entrée invalideDécider comment rejeter ou récupérer le documentDécider si un enregistrement incorrect arrête le traitement ou est isolé
Schéma et livraisonÀ définir séparémentÀ définir séparément

Partez du système consommateur. Renommer data.json en data.jsonl ne convertit pas le fichier. Une API qui attend un tableau peut refuser une suite d’objets pourtant valides. De même, un outil d’import peut considérer un tableau JSON sur une ligne comme une seule valeur, plutôt que plusieurs enregistrements.

JSONL facilite l’écriture d’un itérateur simple. JSON n’impose cependant pas de charger tout le jeu de données en mémoire : des analyseurs spécialisés peuvent lire progressivement de grands documents JSON. Aucune extension ne garantit un gain de vitesse pour votre charge. Mesurez ensemble l’analyse, les transformations, la sortie et les transferts.

Comprendre les limites des documents et des lignes

Un document JSON contient une valeur ; un tableau peut regrouper plusieurs enregistrements. La norme JSON autorise les objets, tableaux, chaînes, nombres, booléens et la valeur null. Voici deux valeurs dans un seul tableau :

[
  {"id":"001","note":"first\nsecond"},
  null
]

La suite équivalente en JSONL n’a ni tableau englobant ni virgule entre les valeurs :

{"id":"001","note":"first\nsecond"}
null

Les règles de JSON Lines imposent UTF-8 sans marque d’ordre des octets et une valeur JSON valide par ligne. Une ligne vide est invalide ; null est valide. Les terminaisons LF et CRLF conviennent. Un saut de ligne final est recommandé, sans être obligatoire.

Le \n échappé d’une chaîne reste dans son enregistrement ; un saut de ligne littéral sépare les lignes physiques. Mettre en forme un objet sur plusieurs lignes casse donc cette disposition. Un pipeline peut exiger des objets avec des champs précis, mais cette règle appartient à son schéma. JSONL autorise aussi les scalaires et les tableaux.

Essayer un lecteur et un générateur Python

Enregistrez le code suivant dans jsonl_records.py. Il utilise uniquement la bibliothèque standard de Python. La démonstration crée des fichiers temporaires, compare un tableau JSON à une suite JSONL, puis supprime ses fichiers. Les six valeurs comprennent volontairement de l’Unicode, un saut de ligne échappé, null, un tableau imbriqué, un nombre et une chaîne.

"""Local JSON/JSONL comparison; standard library, no network access."""
import json
import math
from pathlib import Path
from tempfile import TemporaryDirectory


def check_limit(limit):
    if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
        raise ValueError("max_line_bytes must be a positive integer")


def unique_object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError("duplicate object key")
        result[key] = value
    return result


def reject_constant(text):
    raise ValueError("non-finite constant")


def finite_float(text):
    value = float(text)
    if not math.isfinite(value):
        raise ValueError("outside finite float range")
    return value


def read_jsonl(stream, max_line_bytes=65536):
    """Read a binary stream. The byte limit includes LF or CRLF, if present."""
    check_limit(max_line_bytes)
    line_number = 0
    while True:
        raw = stream.readline(max_line_bytes + 1)
        if not raw:
            return
        line_number += 1
        if len(raw) > max_line_bytes:
            raise ValueError(f"line {line_number}: byte limit exceeded")
        try:
            if raw.startswith(b"\xef\xbb\xbf"):
                raise ValueError("BOM not allowed")
            text = raw.decode("utf-8")
            if not text.strip():
                raise ValueError("blank line")
            value = json.loads(text, object_pairs_hook=unique_object,
                               parse_constant=reject_constant,
                               parse_float=finite_float)
        except (ValueError, RecursionError):
            raise ValueError(
                f"line {line_number}: invalid JSONL or reader policy violation"
            ) from None
        yield value


def write_jsonl(path, records, max_line_bytes=65536):
    """Create a new file; failures can leave a partial output file."""
    check_limit(max_line_bytes)
    with open(path, "xb") as target:
        for value in records:
            text = json.dumps(value, ensure_ascii=False, allow_nan=False,
                              separators=(",", ":"))
            raw = (text + "\n").encode("utf-8")
            if len(raw) > max_line_bytes:
                raise ValueError("output line byte limit exceeded")
            target.write(raw)


def main():
    records = [
        {"id": "001", "note": "first\nsecond", "city": "Zürich"},
        None,
        {"active": True, "count": 0},
        [1, 2],
        3.5,
        "ready",
    ]
    with TemporaryDirectory() as directory:
        root = Path(directory)
        whole = root / "records.json"
        lines = root / "records.jsonl"
        whole.write_text(json.dumps(records, ensure_ascii=False, allow_nan=False),
                         encoding="utf-8")
        write_jsonl(lines, records)
        with whole.open(encoding="utf-8") as source:
            from_json = json.load(source)
        with lines.open("rb") as source:
            from_jsonl = list(read_jsonl(source))  # Six-value test fixture only.
        assert from_json == from_jsonl == records
        physical_lines = lines.read_bytes().count(b"\n")
        assert physical_lines == len(records)
        print("6 values match in JSON and JSONL")
        print(f"JSONL physical lines: {physical_lines}")
        print("Escaped newline preserved:", from_jsonl[0]["note"] == "first\nsecond")


if __name__ == "__main__":
    main()

Lancez-le avec Python 3.12 :

python jsonl_records.py

Sortie attendue :

6 values match in JSON and JSONL
JSONL physical lines: 6
Escaped newline preserved: True

L’appel list(...) sert uniquement à comparer ces six valeurs de test. Dans un traitement, parcourez read_jsonl(source) et traitez chaque valeur sans accumuler le fichier entier. Le lecteur attend un flux binaire. Sa limite par défaut de 65 536 octets est un choix d’exemple, pas une limite du format JSONL ; adaptez-la au destinataire.

Comprendre la portée des vérifications

Les 16 tests couvrent les allers-retours, les fins de ligne, l’absence de saut final, les lignes vides ou mal formées, l’UTF-8 invalide, les marques d’ordre des octets, les règles numériques, les clés répétées, les seuils en octets, la lecture progressive et les échecs d’écriture. Un test de ligne surdimensionnée vérifie que le lecteur demande et reçoit seulement la limite plus un octet d’un flux en mémoire avant de la rejeter. Ce contrôle de comportement n’est pas un benchmark mémoire.

La limite inclut la terminaison LF ou CRLF présente. Les chaînes décodées et les objets Python occupent de la mémoire supplémentaire ; une imbrication profonde peut atteindre les limites de l’analyseur. Le générateur encode une valeur avant de vérifier sa taille : sa limite ne plafonne donc pas les allocations préalables. Utilisez des valeurs compatibles JSON et des clés de dictionnaire textuelles. Cet exemple ne valide aucun schéma métier et ne préserve pas tous les types Python possibles.

La documentation JSON de Python décrit les mécanismes de personnalisation employés ici. Ce lecteur rejette les constantes non finies et les clés d’objet répétées. Cette dernière règle d’interopérabilité est volontairement plus stricte que la syntaxe JSON. Il rejette aussi 1e400, qui dépasse sa plage de nombres flottants finis, alors que ce nombre est syntaxiquement valide en JSON.

Les valeurs du jeu de test survivent à l’aller-retour ; cela ne garantit pas une précision décimale arbitraire. Pour des données financières ou scientifiques, convenez de la plage et de la représentation numériques avec l’application destinataire avant de configurer l’analyseur.

Choisir une politique d’erreur et de reprise

Le lecteur s’arrête à la première ligne incorrecte et indique son numéro sans recopier l’enregistrement dans le message d’erreur. L’échec reste visible, sans ajouter inutilement les données sources aux journaux. Si un traitement isole plutôt les enregistrements rejetés, consignez leur nombre et le motif, limitez l’accès à ces données et décidez à partir de combien d’erreurs le traitement doit échouer.

Le générateur crée un fichier neuf et refuse d’écraser un fichier existant. Il n’est pas transactionnel : si une valeur ultérieure échoue, les lignes précédentes restent dans la sortie. Écartez ce fichier partiel des entrées du consommateur. En production, prévoyez un signal de fin ainsi qu’une politique de nettoyage ou de relance des traitements interrompus.

Pour permettre une reprise, associez le point de contrôle à une version précise de la source et aux effets déjà validés du traitement. Un numéro de ligne seul ne prouve pas qu’une sortie a été enregistrée et ne protège pas contre une source modifiée. Garantir un traitement exactement une fois exige une coordination au-delà du choix de JSONL.

Pour un usage concret lié aux journaux, le guide de supervision des LLM inclut un outil local d’analyse de fichiers d’audit. Un autre consommateur, comme le chargeur de données du guide de fine-tuning LoRA, impose ses propres champs. Partager une extension ne rend pas ces enregistrements interchangeables.

Distinguer écriture locale et envoi d’objets

Un fichier local et un objet distant n’offrent pas les mêmes opérations. Ne supposez pas qu’un objet permet les mêmes ajouts en fin de fichier qu’un fichier local. Pour un traitement par lots, une approche simple consiste à créer un fichier local neuf, le valider, le fermer, puis envoyer le résultat complet sous une nouvelle clé d’objet.

Donnez aux consommateurs un moyen explicite d’identifier les fichiers terminés. Consignez la version du schéma, le nombre d’enregistrements et une somme de contrôle lorsque c’est utile. Testez séparément les échecs d’envoi, les nouvelles tentatives et la publication du signal de fin. L’exemple ci-dessus s’arrête aux fichiers locaux et ne valide pas ces opérations distantes.

Lorsque vous réunissez des fichiers, vérifiez leur jonction : l’absence de saut de ligne final peut fusionner deux enregistrements. Vérifiez aussi qu’ils suivent le même schéma applicatif et les mêmes règles numériques. Pouvoir analyser chaque ligne ne prouve pas que les données ont une signification cohérente.

Traiter les enregistrements avec Hivenet

Compute avec Hivenet fournit une infrastructure CPU pour les traitements exploités par le client. Le stockage objet avec Hivenet fournit un stockage compatible S3 pour les jeux de données et fichiers applicatifs. Le lecteur, les règles de validation, la planification et les reprises restent des composants de votre charge.

Avant de choisir une capacité, réunissez un fichier représentatif, la taille maximale attendue d’un enregistrement, le volume quotidien, le délai de traitement et les exigences du destinataire. Utilisez ces éléments pour tester un traitement CPU et sa connexion au stockage. Six enregistrements locaux permettent de vérifier un comportement, pas de dimensionner une instance de production.

Votre prochaine charge de travail sur Hivenet.

Choisissez une charge de travail d’IA, de calcul ou de stockage à tester sur Hivenet, ou échangez avec notre équipe sur sa mise en production.