Guide complet NDJSON : Newline Delimited JSON expliqué

La spécification NDJSON

La spécification officielle NDJSON sur github.com/ndjson/ndjson-spec est intentionnellement minimaliste. Elle définit une convention simple pour sérialiser plusieurs valeurs JSON dans un seul flux texte. Les règles fondamentales sont simples :

La spécification évite délibérément d’ajouter des en-têtes, des métadonnées ou des informations de schéma au format. Cela maintient NDJSON aussi simple que possible et compatible avec les outils standard de traitement de texte Unix. Toute valeur JSON valide est autorisée sur chaque ligne, bien qu’en pratique la plupart des fichiers NDJSON contiennent des objets JSON avec un ensemble cohérent de clés.

• 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 retour à la ligne '\n' (U+000A). Le retour chariot '\r' (U+000D) peut apparaître avant '\n' mais n’est pas obligatoire.
• Un retour à la ligne final après la dernière valeur JSON est autorisé mais non requis.
• Chaque valeur JSON ne doit pas contenir de caractères de retour à la ligne non échappés au sein de la valeur elle-même.

Comme les règles sont minimales, NDJSON est facile à générer depuis n’importe quel langage de programmation disposant d’un sérialiseur JSON. Sérialisez simplement chaque enregistrement, ajoutez un retour à la ligne et écrivez-le dans la sortie. Pas de crochets fermants, pas de virgules finales, pas de structure de tableau englobante à gérer.

Type MIME NDJSON : application/x-ndjson

Le type MIME enregistré pour NDJSON est application/x-ndjson. Ce type de contenu est utilisé dans les en-têtes HTTP pour indiquer que le corps de la réponse contient des données JSON délimitées par des retours à la ligne. De nombreuses API en streaming, dont l’API GitHub, l’API Docker Registry et l’API bulk d’Elasticsearch, utilisent ce type MIME pour délivrer des réponses NDJSON.

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 également application/json-seq (RFC 7464) ou text/plain comme alternatives. Cependant, application/x-ndjson est le type MIME le plus largement adopté pour les flux JSON délimités par des retours à la ligne. Lors de la création d’une nouvelle API qui diffuse des enregistrements JSON, utilisez application/x-ndjson pour une compatibilité maximale.

NDJSON dans les API HTTP en streaming

NDJSON est le standard de facto pour les API HTTP en streaming qui délivrent des données en temps réel. Lorsqu’un serveur envoie une réponse NDJSON, le client peut commencer à traiter le premier enregistrement dès son arrivée, sans attendre que la réponse complète soit terminée. C’est plus rapide et plus efficace en mémoire que de retourner un grand tableau JSON.

Parmi les services populaires qui utilisent le streaming NDJSON, on trouve Docker Registry (événements de couches d’images), Elasticsearch (opérations en masse), Apache CouchDB (flux de modifications) et de nombreuses API modernes événementielles. Le pattern fonctionne bien avec les alternatives aux Server-Sent Events, le suivi de logs en temps réel et le chargement progressif de données dans les applications web.

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);

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);
}

NDJSON et JSONL : interopérabilité

NDJSON et JSONL (JSON Lines) sont des formats fonctionnellement identiques. Les deux stockent une valeur JSON par ligne, séparée par des caractères de retour à la ligne. Un fichier NDJSON valide est aussi un fichier JSONL valide, et vice versa. Vous pouvez renommer un fichier .ndjson en .jsonl (ou inversement) sans changer un seul octet de contenu, et tout outil qui lit un format lira l’autre.

Les seules différences sont cosmétiques : NDJSON provient de github.com/ndjson/ndjson-spec et utilise l’extension .ndjson avec le type MIME application/x-ndjson, tandis que JSONL provient de jsonlines.org et utilise l’extension .jsonl. En pratique, la plupart des développeurs traitent les deux noms comme des synonymes. Si votre projet utilise déjà JSONL, il n’y a pas besoin de migrer vers NDJSON, et si une bibliothèque indique qu’elle prend en charge NDJSON, elle fonctionnera avec vos fichiers .jsonl sans aucune modification.