Door Jerry Fan

JSONL vs NDJSON: wat is het verschil?

Een uitgebreide vergelijking van JSONL (JSON Lines) en NDJSON (Newline Delimited JSON): twee namen voor vrijwel hetzelfde formaat, met kleine verschillen die handig zijn om te kennen.

JSONL vs NDJSON in één oogopslag

EigenschapJSONL (JSON Lines)NDJSON
Volledige naamJSON LinesNewline Delimited JSON
Bestandsextensie.jsonl.ndjson
Specificatiejsonlines.org (informeel)github.com/ndjson/ndjson-spec (informele specificatie)
OorsprongOntstaan als conventie binnen de community, populair geworden door tools voor data scienceVoorgesteld door Chris Olah, Thorsten Ball en anderen
Regelscheidingsteken\n (nieuwe regel)\n (nieuwe regel)
MIME-typeapplication/jsonl (onofficieel)application/x-ndjson
StreamingondersteuningJa, regel voor regelJa, regel voor regel
GebruikOpenAI, Hugging Face, ML/AI-ecosysteemElasticsearch, Apache Spark, data engineering

Wat is JSONL (JSON Lines)?

JSONL staat voor JSON Lines en is een tekstformaat waarin elke regel precies één geldige JSON-waarde bevat. De regels worden gescheiden door newline-tekens (\n). Het formaat is populair geworden binnen de communities voor machine learning en data science en heeft een informele specificatie op jsonlines.org.

JSONL-bestanden hebben de extensie .jsonl. Het formaat is inmiddels de standaard voor trainingsdata voor AI en ML. OpenAI vereist .jsonl-bestanden voor fine-tuning en datasets van Hugging Face gebruiken vaak het JSON Lines-formaat.

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

Wat is NDJSON (Newline Delimited JSON)?

NDJSON staat voor Newline Delimited JSON en is een dataformaat met één geldige JSON-waarde per regel, waarbij newline-tekens de regels scheiden. De specificatie staat op github.com/ndjson/ndjson-spec en is vastgelegd om een duidelijker omschreven standaard te bieden voor JSON-data die per regel is gescheiden.

NDJSON-bestanden hebben de extensie .ndjson en het geregistreerde MIME-type application/x-ndjson. Het formaat wordt veel gebruikt voor data engineering, logverwerking en streamingtoepassingen. Onder meer Elasticsearch, Apache Spark en veel HTTP streaming APIs gebruiken NDJSON.

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

Zijn JSONL en NDJSON hetzelfde formaat?

Ja, in de praktijk zijn JSONL en NDJSON functioneel identiek. Beide slaan één JSON-waarde per regel op, met newline-tekens (\n) als scheidingsteken. Een .jsonl-bestand en een .ndjson-bestand met dezelfde data zijn volledig uitwisselbaar. Elke tool die het ene formaat kan lezen, kan ook het andere lezen.

De verschillen zitten alleen in de naamgeving, het gebruik binnen communities en de afspraken over metadata. JSONL (JSON Lines) is ontstaan binnen de community voor data science en machine learning. NDJSON (Newline Delimited JSON) is formeel vastgelegd door de community voor data engineering en webstreaming. Vergelijk het met de Engelse woorden "movie" en "film": ze betekenen hetzelfde, maar in verschillende kringen heeft een andere naam de voorkeur.

Het belangrijkste verschil zit in de bestandsextensie (.jsonl vs .ndjson) en het MIME-type. Het MIME-type van NDJSON (application/x-ndjson) wordt breder herkend en gebruikt bij HTTP-streaming. JSONL-bestanden zijn juist de standaard in AI/ML-workflows. Volg bij je keuze de conventies van je ecosysteem.

Belangrijkste verschillen tussen JSONL en NDJSON

1. Specificatie en gezag

JSONL

Beschreven op jsonlines.org in een beknopte, informele specificatie. De regels zijn eenvoudig: elke regel bevat een geldige JSON-waarde, regels worden gescheiden door '\n' en UTF-8-codering wordt aanbevolen.

NDJSON

Beschreven op github.com/ndjson/ndjson-spec in een iets formelere specificatie. NDJSON vereist expliciet dat elke regel een geldige JSON-waarde bevat en dat het scheidingsteken '\n' is (niet '\r\n'). Een newline aan het einde van het bestand wordt aanbevolen.

2. Bestandsextensie

JSONL

Gebruikt de bestandsextensie .jsonl. Dit is de standaard voor bestanden voor OpenAI-fine-tuning, datasets van Hugging Face en de meeste ML/AI-tools. GitHub en VS Code herkennen .jsonl-bestanden en bieden syntax highlighting.

NDJSON

Gebruikt de bestandsextensie .ndjson. Deze is gangbaar bij tools voor data engineering, de bulk-API's van Elasticsearch en HTTP-responses die worden gestreamd. Veel editors bieden ook syntax highlighting voor .ndjson-bestanden.

3. MIME-type

JSONL

Heeft geen officieel geregistreerd MIME-type. Veelgebruikte onofficiële MIME-types zijn application/jsonl en application/json-lines. In de praktijk gebruiken veel systemen application/jsonl of vallen ze terug op application/json.

NDJSON

Gebruikt application/x-ndjson als MIME-type. Dit wordt breder herkend bij HTTP en wordt gebruikt door Elasticsearch, de streamingstandaard van de Fetch API en diverse webframeworks voor het streamen van responses.

4. Gebruik binnen communities en ecosystemen

JSONL

Is het meest gebruikte formaat binnen het AI/ML-ecosysteem. OpenAI, Anthropic, Google Gemini, Hugging Face en de meeste ML-frameworks gebruiken .jsonl. Onder developers in het algemeen is de term 'JSONL' bekender en wordt er vaker op gezocht.

NDJSON

Heeft de voorkeur bij data engineering en backendsystemen. Elasticsearch, Apache Spark, PostgreSQL COPY en veel tools voor logaggregatie gebruiken NDJSON. Het npm-pakket ndjson wordt wekelijks miljoenen keren gedownload.

Wanneer kies je JSONL en wanneer NDJSON?

JSONLGebruik .jsonl als je:
  • Trainingsdata voorbereidt voor fine-tuning bij OpenAI, Anthropic of andere aanbieders van LLMs
  • Met datasets van Hugging Face werkt
  • ML-pipelines bouwt en data voorbewerkt
  • Binnen je team of in je documentatie de term 'JSON Lines' gebruikt
  • Bestanden uploadt naar AI/ML-platforms die de extensie .jsonl verwachten
  • In Python-omgevingen voor data science werkt
NDJSONGebruik .ndjson als je:
  • JSON-data via HTTP streamt (Server-Sent Events, fetch streaming)
  • Met de bulk-API van Elasticsearch werkt
  • Datapipelines bouwt met Apache Spark of vergelijkbare tools
  • Content-Type-headers instelt (application/x-ndjson)
  • Voor je infrastructuur of binnen je team de NDJSON-conventie hanteert
  • Met streaminglibraries voor Node.js werkt

Codevoorbeelden: JSONL en NDJSON lezen

Een .jsonl-bestand lezen (Python)
# JSONL lezen - precies hetzelfde als NDJSON lezen
import json


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


# Output:
# Hello world
# How are you?
# Goodbye
Een .ndjson-bestand lezen (JavaScript/Node.js)
// NDJSON lezen - precies hetzelfde als JSONL lezen
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);
}


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

Bekijk JSONL- en NDJSON-bestanden direct

Open .jsonl- en .ndjson-bestanden tot 1GB in je browser. Je hoeft niets te uploaden of je te registreren. Beide formaten werken zonder problemen.

Veelgestelde vragen

Bronnen