Par Jerry Fan

Guide complet du NDJSON : comprendre Newline Delimited JSON

Découvrez le format Newline Delimited JSON (NDJSON) : sa spécification, son type MIME, la lecture et l’écriture de fichiers en Python, en Node.js et en ligne de commande, son utilisation dans les API HTTP en streaming et ses liens avec JSONL.

Qu’est-ce que NDJSON ?

NDJSON signifie Newline Delimited JSON. Ce format de données textuel contient exactement une valeur JSON valide par ligne, les lignes étant séparées par un caractère de saut de ligne (\n). Il a été conçu pour le streaming et le traitement de grands jeux de données sans charger tout le fichier en mémoire. Là où un fichier JSON standard regroupe toutes les données dans un seul tableau ou objet, NDJSON permet de lire, d’écrire et de traiter les enregistrements un par un.

La spécification NDJSON est hébergée sur github.com/ndjson/ndjson-spec. Elle formalise une pratique déjà courante pour l’acheminement des logs, les pipelines de données et les API HTTP en streaming. Chaque ligne est indépendante : si l’une contient du JSON invalide, les autres restent lisibles. Cette tolérance aux erreurs rend NDJSON particulièrement adapté aux traitements qui ajoutent des données sans modifier l’existant, comme les logs d’application, les flux d’événements et les exports incrémentiels de données.

Exemple de NDJSON (3 enregistrements)
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}

La spécification NDJSON

La spécification officielle de NDJSON, disponible sur github.com/ndjson/ndjson-spec, est volontairement minimaliste. Elle définit une convention simple pour sérialiser plusieurs valeurs JSON dans un même flux texte. Voici les règles essentielles :

La spécification exclut délibérément les en-têtes, les métadonnées et les informations de schéma du format. NDJSON reste ainsi aussi simple que possible et compatible avec les outils Unix standard de traitement de texte. Chaque ligne peut contenir n’importe quelle valeur JSON valide, même si, en pratique, la plupart des fichiers NDJSON contiennent des objets JSON dont les clés sont cohérentes d’un enregistrement à l’autre.

  • Chaque ligne DOIT contenir exactement une valeur JSON valide (objet, tableau, chaîne, nombre, booléen ou null).
  • Les lignes sont séparées par le caractère de saut de ligne '\n' (U+000A). Un retour chariot '\r' (U+000D) peut précéder '\n', mais il n’est pas obligatoire.
  • Un saut de ligne après la dernière valeur JSON est autorisé, mais facultatif.
  • Une valeur JSON ne doit contenir aucun caractère de saut de ligne non échappé.

Avec aussi peu de règles, il est facile de générer du NDJSON dans tout langage de programmation disposant d’un sérialiseur JSON. Il suffit de sérialiser chaque enregistrement, d’y ajouter un saut de ligne et d’écrire le tout en sortie. Aucun crochet fermant, aucune virgule finale ni aucun tableau englobant à gérer.

NDJSON vs JSON vs JSONL

NDJSON, JSON et JSONL se distinguent par leur structure. Le JSON standard encode une seule valeur, généralement un tableau ou un objet. JSONL et NDJSON stockent tous deux une valeur JSON par ligne et sont fonctionnellement identiques. Le tableau ci-dessous présente les principales différences entre ces trois formats.

CaractéristiqueJSONJSONLNDJSON
Nom completJavaScript Object NotationJSON LinesNewline Delimited JSON
Extension de fichier.json.jsonl.ndjson
Type MIMEapplication/jsonapplication/jsonl (non officiel)application/x-ndjson
SpécificationRFC 8259 (norme IETF)jsonlines.org (communauté)github.com/ndjson/ndjson-spec (communauté)
Séparateur de lignesSans objet (valeur unique)\n (saut de ligne)\n (saut de ligne)
Saut de ligne finalN/ARecommandéFacultatif
Adapté au streamingNon (nécessite d’analyser tout le document)Oui (ligne par ligne)Oui (ligne par ligne)

Type MIME de NDJSON : application/x-ndjson

Le type MIME enregistré pour NDJSON est application/x-ndjson. Il sert à indiquer, dans les en-têtes HTTP, que le corps de la réponse contient des valeurs JSON séparées par des sauts de ligne. De nombreuses API en streaming, notamment l’API GitHub, l’API Docker Registry et l’API bulk d’Elasticsearch, l’utilisent pour envoyer des réponses NDJSON.

En-tête HTTP Content-Type
Content-Type: application/x-ndjson


# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream


# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');

Certaines API acceptent aussi application/json-seq (RFC 7464) ou text/plain. Toutefois, application/x-ndjson reste le type MIME le plus répandu pour les flux de valeurs JSON séparées par des sauts de ligne. Si vous créez une API qui diffuse des enregistrements JSON en streaming, utilisez application/x-ndjson pour assurer une compatibilité maximale.

Lire et écrire du NDJSON

Manipuler du NDJSON est simple dans tout langage prenant en charge JSON. Voici des exemples concrets en Python, en Node.js et en ligne de commande.

Le module json de la bibliothèque standard de Python permet de manipuler facilement du NDJSON. Lisez le fichier ligne par ligne, analysez chaque ligne avec json.loads et utilisez json.dumps pour l’écriture. Pour les fichiers volumineux, cette approche ligne par ligne conserve une consommation mémoire constante.

Python : lire et écrire du NDJSON
import json


# Read NDJSON
records = []
with open('data.ndjson', 'r') as f:
    for line in f:
        line = line.strip()
        if line:
            records.append(json.loads(line))


print(f'Loaded {len(records)} records')


# Write NDJSON
output = [
    {'id': 1, 'event': 'page_view', 'url': '/home'},
    {'id': 2, 'event': 'click', 'url': '/pricing'},
    {'id': 3, 'event': 'signup', 'url': '/register'},
]


with open('output.ndjson', 'w') as f:
    for record in output:
        f.write(json.dumps(record) + '\n')

En Node.js, associez le module readline à fs.createReadStream pour analyser efficacement les fichiers NDJSON. Le flux traite les lignes une à une, ce qui limite la consommation mémoire, quelle que soit la taille du fichier.

Node.js : lire et écrire du NDJSON
import { createReadStream, writeFileSync } from 'node:fs';
import { createInterface } from 'node:readline';


// Read NDJSON
async function readNdjson(filePath) {
  const records = [];
  const rl = createInterface({
    input: createReadStream(filePath, 'utf-8'),
    crlfDelay: Infinity,
  });
  for await (const line of rl) {
    const trimmed = line.trim();
    if (trimmed) records.push(JSON.parse(trimmed));
  }
  return records;
}


// Write NDJSON
const data = [
  { id: 1, event: 'page_view' },
  { id: 2, event: 'click' },
];
const ndjson = data.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync('output.ndjson', ndjson, 'utf-8');

L’outil en ligne de commande jq prend nativement en charge les données NDJSON en entrée. Utilisez l’option --slurp pour réunir tous les enregistrements dans un tableau, ou traitez-les un par un sans ajouter d’option.

Ligne de commande : traiter du NDJSON avec jq
# Print each record (jq reads NDJSON by default)
jq '.' data.ndjson


# Filter records where event is "click"
jq 'select(.event == "click")' data.ndjson


# Extract specific fields
jq '{id, url}' data.ndjson


# Count total records
jq -s 'length' data.ndjson


# Convert NDJSON to a JSON array
jq -s '.' data.ndjson > data.json


# Convert a JSON array back to NDJSON
jq -c '.[]' data.json > data.ndjson

NDJSON dans les API HTTP en streaming

NDJSON est le standard de fait des API HTTP en streaming qui transmettent des données en temps réel. Lorsqu’un serveur envoie une réponse NDJSON, le client peut traiter le premier enregistrement dès sa réception, sans attendre la fin de la réponse. Cette approche est plus rapide et consomme moins de mémoire que le renvoi d’un grand tableau JSON.

Parmi les services courants utilisant le streaming NDJSON figurent Docker Registry (événements liés aux couches d’images), Elasticsearch (opérations en masse), Apache CouchDB (flux de modifications) et de nombreuses API modernes reposant sur des événements. Cette approche se prête bien aux solutions alternatives aux Server-Sent Events, au suivi des logs en temps réel et au chargement progressif des données dans les applications web.

Serveur de streaming NDJSON avec Express.js
import express from 'express';


const app = express();


app.get('/api/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');


  // Simulate streaming events
  let id = 0;
  const interval = setInterval(() => {
    id++;
    const event = {
      id,
      type: 'heartbeat',
      timestamp: new Date().toISOString(),
    };
    res.write(JSON.stringify(event) + '\n');


    if (id >= 100) {
      clearInterval(interval);
      res.end();
    }
  }, 100);


  req.on('close', () => clearInterval(interval));
});


app.listen(3000);
Navigateur : lire un flux NDJSON avec Fetch
async function* readNdjsonStream(url) {
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-ndjson' },
  });


  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();


  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (line.trim()) yield JSON.parse(line);
    }
  }
  if (buffer.trim()) yield JSON.parse(buffer);
}


// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
  console.log('Received:', event);
}

Outils de l’écosystème NDJSON

De plus en plus d’outils en ligne de commande et de bibliothèques prennent nativement en charge NDJSON. Ils permettent de filtrer, de transformer et d’analyser des données NDJSON sans écrire de code spécifique.

jq

Essentiel

jq est l’outil de traitement JSON en ligne de commande le plus populaire. Il lit le NDJSON par défaut (une valeur JSON par ligne) et permet de filtrer, de transformer, de regrouper et de reformater les données. Utilisez jq -c pour obtenir une sortie compacte et jq -s pour réunir tous les enregistrements dans un tableau.

ndjson-cli

CLI

ndjson-cli regroupe des commandes de type Unix pour manipuler des flux NDJSON : ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort et ndjson-join. Chaque commande lit sur stdin et écrit sur stdout, ce qui permet de les enchaîner avec des pipes.

ndjson (npm)

Node.js

Le package npm ndjson fournit des parseurs et des sérialiseurs NDJSON en streaming pour Node.js. Il expose les flux de transformation ndjson.parse() et ndjson.stringify(), qui s’intègrent directement aux pipelines de streams Node.js pour traiter les données à haut débit.

NDJSON et JSONL : interopérabilité

NDJSON et JSONL (JSON Lines) sont fonctionnellement identiques. Ils stockent tous deux une valeur JSON par ligne, avec un saut de ligne comme séparateur. Un fichier NDJSON valide est aussi un fichier JSONL valide, et inversement. Vous pouvez renommer un fichier .ndjson en .jsonl (ou l’inverse) sans modifier un seul octet de son contenu : tout outil capable de lire l’un de ces formats saura lire l’autre.

Les différences ne portent que sur la présentation : NDJSON est défini sur github.com/ndjson/ndjson-spec et utilise l’extension .ndjson ainsi que le type MIME application/x-ndjson, tandis que JSONL est défini sur jsonlines.org et utilise l’extension .jsonl. En pratique, la plupart des développeurs emploient ces deux noms comme des synonymes. Si votre projet utilise déjà JSONL, aucune migration vers NDJSON n’est nécessaire. De même, une bibliothèque qui prend en charge NDJSON fonctionnera avec vos fichiers .jsonl sans modification.

JSONL vs NDJSON : comparaison détaillée

Pour en savoir plus sur l’histoire de JSONL et de NDJSON, les différences entre leurs spécifications et leur adoption par la communauté, consultez notre guide comparatif.

Travaillez avec des fichiers NDJSON en ligne

Visualisez, validez et convertissez des fichiers NDJSON et JSONL jusqu’à 1 Go directement dans votre navigateur. Aucun fichier à envoyer : vos données restent 100 % privées.

Questions fréquentes

Références