Par Jerry Fan

JSONL vs NDJSON : quelle est la différence ?

Un guide complet pour comparer JSONL (JSON Lines) et NDJSON (Newline Delimited JSON) : deux noms pour un format presque identique, avec quelques nuances à connaître.

JSONL vs NDJSON en un coup d’œil

CaractéristiqueJSONL (JSON Lines)NDJSON
Nom completJSON LinesNewline Delimited JSON
Extension de fichier.jsonl.ndjson
Spécificationjsonlines.org (informelle)github.com/ndjson/ndjson-spec (spécification informelle)
OrigineConvention issue de la communauté, popularisée par les outils de data scienceProposé par Chris Olah, Thorsten Ball et d’autres
Séparateur de lignes\n (retour à la ligne)\n (retour à la ligne)
Type MIMEapplication/jsonl (non officiel)application/x-ndjson
Prise en charge du streamingOui, ligne par ligneOui, ligne par ligne
AdoptionOpenAI, Hugging Face, écosystème IA/MLElasticsearch, Apache Spark, data engineering

Qu’est-ce que JSONL (JSON Lines) ?

JSONL, abréviation de JSON Lines, est un format de données textuel dans lequel chaque ligne contient une seule valeur JSON valide. Les lignes sont séparées par des caractères de saut de ligne (\n). Popularisé par les communautés du machine learning et de la data science, ce format est décrit dans une spécification informelle sur jsonlines.org.

Les fichiers JSONL portent l’extension .jsonl. Ce format s’est imposé comme le standard pour les données d’entraînement en IA et en machine learning : OpenAI exige des fichiers .jsonl pour le fine-tuning, et les jeux de données Hugging Face utilisent couramment le format JSON Lines.

data.jsonl
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}

Qu’est-ce que NDJSON (Newline Delimited JSON) ?

NDJSON, ou Newline Delimited JSON, est un format de données dans lequel chaque ligne contient une valeur JSON valide, les lignes étant séparées par des caractères de saut de ligne. Sa spécification, hébergée sur github.com/ndjson/ndjson-spec, a été formalisée pour donner un cadre plus structuré aux données JSON organisées ligne par ligne.

Les fichiers NDJSON portent l’extension .ndjson et disposent d’un type MIME enregistré : application/x-ndjson. Ce format est largement utilisé en data engineering, pour le traitement des logs et dans les applications de streaming. Elasticsearch, Apache Spark et de nombreuses API HTTP en streaming utilisent NDJSON.

data.ndjson
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}

JSONL et NDJSON désignent-ils le même format ?

En pratique, oui : JSONL et NDJSON sont fonctionnellement identiques. Tous deux stockent une valeur JSON par ligne, avec des caractères de saut de ligne (\n) comme séparateurs. Un fichier .jsonl et un fichier .ndjson contenant les mêmes données sont parfaitement interchangeables, et tout outil capable de lire l’un peut lire l’autre.

Les différences tiennent uniquement au nom, aux communautés qui les utilisent et aux conventions relatives aux métadonnées. JSONL (JSON Lines) est né dans la communauté de la data science et du machine learning, tandis que NDJSON (Newline Delimited JSON) a été formalisé par celle du data engineering et du streaming web. C’est un peu comme les mots anglais « movie » et « film » : ils désignent la même chose, mais leur usage varie selon les milieux.

Les différences les plus concrètes concernent l’extension du fichier (.jsonl ou .ndjson) et le type MIME. NDJSON dispose d’un type MIME plus largement reconnu (application/x-ndjson), utilisé pour le streaming HTTP, tandis que les fichiers JSONL sont le standard dans les workflows IA/ML. Pour choisir, suivez les conventions de votre écosystème.

Les principales différences entre JSONL et NDJSON

1. Spécification et référence

JSONL

JSONL est défini sur jsonlines.org par une spécification courte et informelle. Les règles sont simples : chaque ligne contient une valeur JSON valide, les lignes sont séparées par '\n', et l’encodage UTF-8 est recommandé.

NDJSON

NDJSON est défini sur github.com/ndjson/ndjson-spec par une spécification un peu plus formelle. Celle-ci exige explicitement que chaque ligne contienne une valeur JSON valide et que le séparateur soit '\n' (et non '\r\n'). Un saut de ligne final est recommandé.

2. Extension de fichier

JSONL

JSONL utilise l’extension .jsonl. C’est le standard pour les fichiers de fine-tuning OpenAI, les jeux de données Hugging Face et la plupart des outils de machine learning et d’IA. GitHub et VS Code reconnaissent les fichiers .jsonl et proposent la coloration syntaxique.

NDJSON

NDJSON utilise l’extension .ndjson, courante dans les outils de data engineering, les API bulk d’Elasticsearch et les réponses HTTP en streaming. De nombreux éditeurs proposent également la coloration syntaxique pour les fichiers .ndjson.

3. Type MIME

JSONL

JSONL n’a pas de type MIME officiellement enregistré. Les types non officiels les plus courants sont application/jsonl et application/json-lines. En pratique, de nombreux systèmes utilisent application/jsonl ou, à défaut, application/json.

NDJSON

NDJSON utilise le type MIME application/x-ndjson. Plus largement reconnu dans les échanges HTTP, ce type est utilisé par Elasticsearch, le standard de streaming de l’API Fetch et divers frameworks web pour les réponses en streaming.

4. Adoption par les communautés et les écosystèmes

JSONL

JSONL domine dans l’écosystème IA/ML. OpenAI, Anthropic, Google Gemini, Hugging Face et la plupart des frameworks de machine learning utilisent .jsonl. Dans l’ensemble de la communauté des développeurs, le terme « JSONL » est plus connu et fait plus souvent l’objet de recherches.

NDJSON

NDJSON est privilégié en data engineering et dans les systèmes backend. Elasticsearch, Apache Spark, PostgreSQL COPY et de nombreux outils d’agrégation de logs utilisent NDJSON. Le package npm ndjson est téléchargé des millions de fois par semaine.

Quand utiliser JSONL ou NDJSON ?

JSONLUtilisez .jsonl dans les cas suivants :
  • Vous préparez des données d’entraînement pour le fine-tuning de LLM chez OpenAI, Anthropic ou d’autres fournisseurs
  • Vous travaillez avec des jeux de données Hugging Face
  • Vous développez des pipelines de machine learning et préparez les données en amont
  • Votre équipe ou votre documentation emploie le terme « JSON Lines »
  • Vous envoyez des fichiers vers des plateformes IA/ML qui exigent l’extension .jsonl
  • Vous travaillez dans des environnements de data science en Python
NDJSONUtilisez .ndjson dans les cas suivants :
  • Vous transmettez des données JSON en streaming sur HTTP (Server-Sent Events, streaming avec fetch)
  • Vous utilisez l’API bulk d’Elasticsearch
  • Vous développez des pipelines de données avec Apache Spark ou des outils similaires
  • Vous définissez des en-têtes Content-Type (application/x-ndjson)
  • Votre infrastructure ou votre équipe suit la convention NDJSON
  • Vous utilisez des bibliothèques de streaming Node.js

Exemples de code : lire des fichiers JSONL et NDJSON

Lire un fichier .jsonl (Python)
# Lecture JSONL - exactement comme la lecture NDJSON
import json


with open('data.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line.strip())
        print(record['text'])


# Sortie :
# Hello world
# How are you?
# Goodbye
Lire un fichier .ndjson (JavaScript/Node.js)
// Lecture NDJSON - exactement comme la lecture JSONL
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.ndjson')
});


for await (const line of rl) {
  const record = JSON.parse(line);
  console.log(record.text);
}


// Sortie :
// Hello world
// How are you?
// Goodbye

Consultez vos fichiers JSONL et NDJSON instantanément

Ouvrez des fichiers .jsonl et .ndjson jusqu’à 1 Go directement dans votre navigateur. Aucun envoi de fichier, aucune inscription : les deux formats sont pris en charge sans manipulation supplémentaire.

Questions fréquentes

Références