Par Jerry Fan

Bonnes pratiques JSONL

Un guide complet pour créer des fichiers JSONL propres, fiables et performants. Découvrez les règles de formatage, la conception des schémas, les stratégies de gestion des erreurs et les techniques d’optimisation pour les traitements en production.

Pourquoi adopter de bonnes pratiques avec JSONL ?

JSONL (JSON Lines) paraît simple : un objet JSON par ligne, avec un saut de ligne comme séparateur. Cette simplicité n’exclut pourtant pas les pièges. Schémas incohérents, problèmes d’encodage, virgules finales et sauts de ligne dans les valeurs figurent parmi les causes les plus fréquentes d’erreurs de parsing dans les pipelines de données en production. Des bonnes pratiques claires permettent d’éviter ces problèmes à la source.

Ce guide présente les règles essentielles pour produire et exploiter des données JSONL de manière fiable. Que vous constituiez des jeux de données pour le machine learning, transmettiez des logs applicatifs en streaming ou échangiez des données entre services, ces pratiques vous aideront à éviter les bugs difficiles à repérer et à améliorer les performances de vos traitements JSONL.

Règles de formatage

Pour obtenir un fichier JSONL valide, quelques règles de formatage doivent être respectées à la lettre. Il suffit d’en enfreindre une pour que la plupart des parseurs rejettent le fichier.

Chaque ligne d’un fichier JSONL doit contenir une valeur JSON complète et autonome. Ne répartissez jamais un même objet JSON sur plusieurs lignes. Un JSON mis en forme avec une indentation n’est pas du JSONL valide. Utilisez toujours une sérialisation au format compact, sans indentation ni espaces superflus entre les clés et les valeurs.

Un objet JSON par ligne
# Valid JSONL - one complete JSON per line
{"id":1,"name":"Alice","tags":["admin","user"]}
{"id":2,"name":"Bob","tags":["user"]}


# INVALID - pretty-printed JSON spans multiple lines
{
  "id": 1,
  "name": "Alice"
}

Les fichiers JSONL doivent être encodés en UTF-8. C’est l’encodage attendu par la quasi-totalité des parseurs JSONL, des outils de streaming et des services cloud. Évitez UTF-16, Latin-1 et les autres encodages. Si vos données sources utilisent un autre encodage, convertissez-les en UTF-8 avant de les écrire au format JSONL.

Toujours utiliser l’encodage UTF-8
# Python: always specify UTF-8 when reading/writing
with open('data.jsonl', 'w', encoding='utf-8') as f:
    f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Node.js: UTF-8 is the default for fs
fs.appendFileSync('data.jsonl', JSON.stringify(record) + '\n', 'utf-8');

Utilisez un seul caractère de saut de ligne (LF, \n) pour séparer les lignes. C’est la norme sous Linux, sous macOS et dans la plupart des environnements cloud. Évitez la séquence retour chariot + saut de ligne (CRLF, \r\n) utilisée sous Windows, qui peut provoquer des erreurs de parsing. La plupart des éditeurs et outils modernes s’en chargent automatiquement, mais vérifiez vos réglages si vous travaillez sur plusieurs plateformes.

Choisir le bon séparateur de lignes
# Correct: LF line endings (\n)
{"id":1}\n{"id":2}\n


# Avoid: CRLF line endings (\r\n)
{"id":1}\r\n{"id":2}\r\n


# Tip: configure Git to normalize line endings
# .gitattributes
*.jsonl text eol=lf

Cohérence du schéma

JSONL n’impose aucun schéma, mais des enregistrements de structure cohérente sont beaucoup plus faciles à exploiter. Des schémas incohérents entraînent des erreurs à l’exécution, des valeurs null inattendues et des échecs d’importation.

Conservez les mêmes noms de champs, le même ordre et les mêmes types de valeurs dans tous les enregistrements. JSON n’impose pas d’ordre aux champs, mais un ordre constant améliore la lisibilité et facilite la compression. Ne faites jamais varier le type d’un même champ : par exemple, un champ « price » ne doit pas contenir une chaîne dans certains enregistrements et un nombre dans d’autres.

Conserver un ordre et des types de champs cohérents
# Good: consistent field order and types
{"id":1,"name":"Alice","age":30,"active":true}
{"id":2,"name":"Bob","age":25,"active":false}
{"id":3,"name":"Charlie","age":35,"active":true}


# Bad: inconsistent order, mixed types, missing fields
{"name":"Alice","id":1,"active":true}
{"id":"2","age":25,"name":"Bob"}
{"id":3,"active":"yes","name":"Charlie"}

Lorsqu’un champ n’a pas de valeur, conservez sa clé et attribuez-lui la valeur JSON null plutôt que de supprimer la clé. Les traitements en aval sont ainsi plus simples, car tous les enregistrements possèdent les mêmes clés. Le code qui exploite les données n’a plus à distinguer un champ absent d’un champ dont la valeur est null.

Gérer explicitement les valeurs manquantes
# Good: include all fields, use null for missing values
{"id":1,"name":"Alice","email":"[email protected]","phone":null}
{"id":2,"name":"Bob","email":null,"phone":"+1-555-0100"}


# Avoid: omitting keys for missing data
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","phone":"+1-555-0100"}

Gestion des erreurs

En pratique, les fichiers JSONL contiennent souvent quelques lignes invalides à cause de problèmes d’encodage, d’écritures tronquées ou de bugs en amont. Un programme robuste sait gérer ces cas sans planter à la première ligne incorrecte.

Placez le parsing de chaque ligne dans un bloc try-catch et consignez le numéro de ligne ainsi que le message d’erreur à chaque échec. Vous pourrez ainsi ignorer les lignes invalides tout en gardant une trace des problèmes rencontrés. Pour les pipelines critiques, rassemblez ces lignes dans un fichier séparé afin de les examiner plus tard.

Analyse tolérante avec suivi des lignes
import json


def parse_jsonl_safe(path: str):
    """Parse JSONL with error tolerance."""
    valid, errors = [], []
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                valid.append(json.loads(line))
            except json.JSONDecodeError as e:
                errors.append({'line': line_num, 'error': str(e), 'raw': line})
    print(f'Parsed {len(valid)} records, {len(errors)} errors')
    return valid, errors

Dans vos pipelines de données, ajoutez une étape de validation avant le traitement principal. Vérifiez que chaque enregistrement contient les champs attendus et que leurs types sont corrects. Rejetez ou mettez en quarantaine les enregistrements non conformes. Vous éviterez ainsi que des erreurs de type surviennent plus loin dans le pipeline, où elles sont plus difficiles à déboguer.

Valider les données avant de les traiter
def validate_record(record: dict) -> list[str]:
    """Validate a JSONL record against expected schema."""
    issues = []
    required = ['id', 'name', 'timestamp']
    for field in required:
        if field not in record:
            issues.append(f'Missing required field: {field}')
    if 'id' in record and not isinstance(record['id'], int):
        issues.append(f'Field "id" should be int, got {type(record["id"]).__name__}')
    return issues


# Usage in pipeline
for record in parse_jsonl_safe('data.jsonl')[0]:
    issues = validate_record(record)
    if issues:
        log_warning(f'Record {record.get("id")}: {issues}')
    else:
        process(record)

Optimisation des performances

Dans les traitements de data engineering et de machine learning, les fichiers JSONL peuvent atteindre plusieurs gigaoctets. Une stratégie de traitement adaptée permet de maîtriser la consommation mémoire tout en conservant un débit élevé.

Ne chargez jamais un fichier JSONL entier en mémoire. Lisez et traitez les données une ligne ou un lot de lignes à la fois. La consommation mémoire reste ainsi constante, quelle que soit la taille du fichier. En Python, parcourir un fichier se fait naturellement ligne par ligne ; Node.js propose les API readline et stream pour le même usage.

Traitement en streaming
# Python: stream with constant memory
import json


count = 0
with open('large.jsonl', 'r', encoding='utf-8') as f:
    for line in f:  # One line at a time, not f.readlines()!
        record = json.loads(line)
        process(record)
        count += 1
print(f'Processed {count} records')

Pour les écritures en base de données ou les appels API, regroupez plusieurs enregistrements dans un même lot au lieu de les traiter un par un. Le traitement par lots réduit le coût des entrées-sorties et peut multiplier le débit par 10 à 100. Des lots de 1 000 à 10 000 enregistrements conviennent à la plupart des usages.

Traitement par lots
import json


def process_in_batches(path: str, batch_size: int = 5000):
    """Process JSONL records in batches for better throughput."""
    batch = []
    with open(path, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            batch.append(json.loads(line))
            if len(batch) >= batch_size:
                bulk_insert(batch)  # Send batch to database
                batch.clear()
    if batch:
        bulk_insert(batch)  # Flush remaining records

JSONL se compresse très bien, car les lignes qui se suivent contiennent souvent les mêmes clés et des valeurs similaires. Utilisez gzip pour diviser la taille des fichiers par 5 à 10 lors du stockage et du transfert. La plupart des langages permettent de lire directement du JSONL compressé avec gzip, sans décompression préalable sur disque.

Compresser les fichiers pour le stockage et le transfert
import gzip
import json


# Write compressed JSONL
with gzip.open('data.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Read compressed JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        process(record)

Erreurs courantes à éviter

Voici les problèmes que nous rencontrons le plus souvent lorsque les utilisateurs valident leurs fichiers JSONL avec nos outils. Ils provoquent tous des erreurs de parsing qui peuvent être difficiles à diagnostiquer sans une approche adaptée.

JSON n’autorise pas de virgule après le dernier élément d’un objet ou d’un tableau. C’est l’une des erreurs les plus fréquentes, notamment chez les développeurs habitués à JavaScript, où ces virgules sont valides. Supprimez systématiquement les virgules finales dans les données que vous générez.

Virgules finales
# INVALID: trailing comma after last property
{"id": 1, "name": "Alice",}


# VALID: no trailing comma
{"id": 1, "name": "Alice"}


# INVALID: trailing comma in array
{"tags": ["admin", "user",]}


# VALID: no trailing comma in array
{"tags": ["admin", "user"]}

Un caractère de saut de ligne littéral dans une chaîne enfreint la règle d’un enregistrement par ligne et corrompt le fichier JSONL. Dans les chaînes JSON, utilisez toujours la forme échappée \n, jamais un saut de ligne brut. La plupart des sérialiseurs JSON s’en chargent automatiquement, mais soyez vigilant si vous construisez vos chaînes JSON à la main.

Sauts de ligne dans les chaînes de caractères
# INVALID: raw newline inside a string value breaks JSONL
{"id": 1, "bio": "Line one
Line two"}


# VALID: escaped newline keeps everything on one line
{"id": 1, "bio": "Line one\nLine two"}


# Tip: json.dumps() in Python handles this automatically
import json
record = {"bio": "Line one\nLine two"}
print(json.dumps(record))
# Output: {"bio": "Line one\nLine two"}

Mélanger UTF-8 et Latin-1, ou d’autres encodages, dans un même fichier produit des caractères illisibles et des erreurs de parsing. Cela arrive souvent lorsqu’on ajoute des données provenant de sources différentes. Convertissez toujours les données en UTF-8 avant de les écrire. Si leur encodage est inconnu, détectez-le avec une bibliothèque comme chardet avant de les convertir.

Encodages mélangés ou incorrects
# Python: detect and convert encoding
import chardet


def normalize_to_utf8(input_path: str, output_path: str):
    """Detect encoding and convert to UTF-8."""
    with open(input_path, 'rb') as f:
        raw = f.read()
    detected = chardet.detect(raw)
    encoding = detected['encoding'] or 'utf-8'
    print(f'Detected encoding: {encoding}')
    text = raw.decode(encoding)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(text)

Nommage et organisation des fichiers

Des noms de fichiers bien choisis et une arborescence claire facilitent la recherche, la gestion et le traitement des données JSONL dans les pipelines automatisés.

Utilisez .jsonl comme extension par défaut. C’est l’extension la plus largement reconnue pour les fichiers JSON Lines, et celle qu’attendent l’API de fine-tuning d’OpenAI, BigQuery et la plupart des plateformes de données. L’extension .ndjson (Newline Delimited JSON) désigne techniquement le même format sous un autre nom. Choisissez une convention et appliquez-la à l’ensemble du projet.

Extensions .jsonl et .ndjson
# Recommended file naming conventions
data.jsonl              # Standard JSONL file
users_2026-02-14.jsonl  # Date-stamped export
train.jsonl             # ML training data
validation.jsonl        # ML validation split
events.jsonl.gz         # Compressed JSONL

Organisez vos fichiers JSONL par usage et par date. Séparez les données brutes en entrée des données traitées en sortie. Pour les séries temporelles ou les logs, partitionnez les données par date : vous pourrez plus facilement traiter une période précise et supprimer les anciennes données.

Arborescence d’un projet JSONL
project/
  data/
    raw/                  # Original unprocessed files
      events_2026-02-13.jsonl
      events_2026-02-14.jsonl
    processed/            # Cleaned and transformed
      events_clean.jsonl
    schemas/              # Schema documentation
      event_schema.json
  scripts/
    validate.py           # Validation script
    transform.py          # Transformation pipeline

Vérifiez vos fichiers JSONL dès maintenant

Validez et formatez des fichiers JSONL jusqu’à 1 Go directement dans votre navigateur. Repérez instantanément les erreurs de formatage, les incohérences de schéma et les problèmes d’encodage.

Questions fréquentes

Références