Complete gids voor NDJSON: Newline Delimited JSON uitgelegd
Een uitgebreide gids over Newline Delimited JSON (NDJSON). Ontdek hoe de specificatie in elkaar zit, welk MIME-type je gebruikt en hoe je NDJSON leest en schrijft met Python, Node.js en de commandline. Leer ook hoe je het gebruikt in streaming HTTP-API’s en hoe het zich verhoudt tot JSONL.
Wat is NDJSON?
NDJSON staat voor Newline Delimited JSON. Het is een tekstformaat waarin elke regel precies één geldige JSON-waarde bevat. De regels worden gescheiden door een newline-teken (\n). Het formaat is ontworpen om grote datasets te streamen en te verwerken zonder het hele bestand in het geheugen te laden. Een standaard JSON-bestand bevat alles in één array of object; met NDJSON kun je records één voor één lezen, schrijven en verwerken.
De NDJSON-specificatie staat op github.com/ndjson/ndjson-spec. Deze specificatie legt een werkwijze vast die al gangbaar was bij log shipping, datapipelines en streaming HTTP-API’s. Elke regel staat op zichzelf: als één regel ongeldige JSON bevat, kun je de andere regels nog steeds parsen. Daardoor is NDJSON fouttolerant en geschikt voor append-only workflows, zoals applicatielogs, eventstreams en incrementele data-exports.
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}De NDJSON-specificatie
De officiële NDJSON-specificatie op github.com/ndjson/ndjson-spec is bewust beknopt gehouden. De specificatie beschrijft een eenvoudige conventie om meerdere JSON-waarden te serialiseren in één tekststream. De basisregels zijn eenvoudig:
De specificatie voegt bewust geen headers, metadata of schema-informatie aan het formaat toe. Zo blijft NDJSON zo eenvoudig mogelijk en kun je het met standaard Unix-tools voor tekstverwerking gebruiken. Op elke regel mag elke geldige JSON-waarde staan, al bevatten de meeste NDJSON-bestanden in de praktijk JSON-objecten met een vaste set keys.
- Elke regel MOET precies één geldige JSON-waarde bevatten (object, array, string, getal, boolean of null).
- Regels worden gescheiden door het newline-teken '\n' (U+000A). Een carriage return '\r' (U+000D) mag vóór '\n' staan, maar is niet verplicht.
- Een afsluitende newline na de laatste JSON-waarde is toegestaan, maar niet verplicht.
- Een JSON-waarde mag zelf geen newline-tekens bevatten die niet zijn ge-escapet.
Dankzij deze eenvoudige regels kun je NDJSON genereren in elke programmeertaal met een JSON-serializer. Serialiseer elk record, voeg een newline toe en schrijf het resultaat naar de uitvoer. Je hoeft geen rekening te houden met sluitende haakjes, komma’s na het laatste element of een omsluitende array.
NDJSON versus JSON versus JSONL
NDJSON, JSON en JSONL verschillen in hun opbouw. Standaard JSON codeert één waarde, meestal een array of object. JSONL en NDJSON slaan allebei één JSON-waarde per regel op en zijn functioneel identiek. De tabel hieronder laat de belangrijkste verschillen tussen de drie formaten zien.
| Kenmerk | JSON | JSONL | NDJSON |
|---|---|---|---|
| Volledige naam | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| Bestandsextensie | .json | .jsonl | .ndjson |
| MIME-type | application/json | application/jsonl (onofficieel) | application/x-ndjson |
| Specificatie | RFC 8259 (IETF-standaard) | jsonlines.org (gemeenschap) | github.com/ndjson/ndjson-spec (community) |
| Regelscheidingsteken | N.v.t. (één waarde) | \n (newline) | \n (newline) |
| Afsluitende newline | N.v.t. | Aanbevolen | Optioneel |
| Geschikt voor streaming | Nee (het hele document moet worden geparset) | Ja (regel voor regel) | Ja (regel voor regel) |
MIME-type voor NDJSON: application/x-ndjson
Het geregistreerde MIME-type voor NDJSON is application/x-ndjson. Met dit contenttype geef je in HTTP-headers aan dat de responsebody JSON-data bevat waarvan de waarden door newlines worden gescheiden. Veel streaming API’s, waaronder de GitHub API, Docker Registry API en Elasticsearch bulk API, gebruiken dit MIME-type voor NDJSON-responses.
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');Sommige API’s accepteren ook application/json-seq (RFC 7464) of text/plain als alternatief. Voor JSON-streams met newlines als scheidingsteken is application/x-ndjson echter het meest gebruikte MIME-type. Bouw je een nieuwe API die JSON-records streamt, gebruik dan application/x-ndjson voor maximale compatibiliteit.
NDJSON lezen en schrijven
Je kunt eenvoudig met NDJSON werken in elke taal die JSON ondersteunt. Hieronder vind je praktische voorbeelden voor Python, Node.js en de commandline.
Met de ingebouwde json-module van Python kun je eenvoudig NDJSON verwerken. Lees een bestand regel voor regel, parse elke regel met json.loads en schrijf de uitvoer met json.dumps. Ook bij grote bestanden blijft het geheugengebruik met deze aanpak constant.
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')In Node.js gebruik je de readline-module samen met fs.createReadStream om NDJSON-bestanden efficiënt te parsen. De stream verwerkt steeds één regel, waardoor het geheugengebruik laag blijft, ongeacht de bestandsgrootte.
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');De commandlinetool jq ondersteunt NDJSON-invoer standaard. Gebruik de optie --slurp om alle records in één array te verzamelen, of verwerk elk record afzonderlijk zonder die optie.
# 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.ndjsonNDJSON in streaming HTTP-API’s
NDJSON is de de facto standaard voor streaming HTTP-API’s die realtime data leveren. Als een server een NDJSON-response verstuurt, kan de client het eerste record verwerken zodra het binnenkomt. De client hoeft dus niet te wachten tot de volledige response binnen is. Dit is sneller en verbruikt minder geheugen dan het terugsturen van een grote JSON-array.
Bekende diensten die NDJSON-streaming gebruiken, zijn Docker Registry (image layer events), Elasticsearch (bulkoperaties), Apache CouchDB (changes feed) en veel moderne event-driven API’s. Deze aanpak werkt goed voor alternatieven voor Server-Sent Events, het realtime volgen van logs en het stapsgewijs laden van data in webapplicaties.
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);
}Tools voor NDJSON
Een groeiend ecosysteem van commandlinetools en libraries ondersteunt NDJSON standaard. Met deze tools kun je NDJSON-data filteren, transformeren en analyseren zonder zelf code te schrijven.
jq
Essentieeljq is de populairste commandlinetool voor het verwerken van JSON. De tool leest standaard NDJSON (één JSON-waarde per regel) en ondersteunt filteren, mappen, groeperen en het aanpassen van de opmaak. Gebruik jq -c voor compacte uitvoer en jq -s om alle records in één array te verzamelen.
ndjson-cli
CLIndjson-cli is een verzameling commando’s in Unix-stijl voor het bewerken van NDJSON-streams: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort en ndjson-join. Elk commando leest uit stdin en schrijft naar stdout, zodat je ze met pipes aan elkaar kunt koppelen.
ndjson (npm)
Node.jsHet npm-pakket ndjson biedt streaming parsers en serializers voor NDJSON in Node.js. Het pakket stelt de transform streams ndjson.parse() en ndjson.stringify() beschikbaar. Die kun je direct opnemen in Node.js-streampipelines om data met een hoge doorvoer te verwerken.
NDJSON en JSONL: onderlinge uitwisselbaarheid
NDJSON en JSONL (JSON Lines) zijn functioneel identieke formaten. Beide slaan één JSON-waarde per regel op, met newline-tekens als scheidingsteken. Een geldig NDJSON-bestand is ook geldig JSONL, en andersom. Je kunt de extensie van een bestand wijzigen van .ndjson naar .jsonl (of andersom) zonder ook maar één byte van de inhoud te veranderen. Elke tool die het ene formaat kan lezen, kan ook het andere lezen.
De verschillen zitten alleen in de naamgeving: NDJSON komt van github.com/ndjson/ndjson-spec en gebruikt de extensie .ndjson met het MIME-type application/x-ndjson. JSONL komt van jsonlines.org en gebruikt de extensie .jsonl. In de praktijk gebruiken de meeste developers de twee namen als synoniemen. Gebruikt je project al JSONL, dan hoef je niet naar NDJSON te migreren. En als een library NDJSON ondersteunt, werkt die zonder aanpassingen met je .jsonl-bestanden.
Probeer onze gratis NDJSON/JSONL-tools
Werk rechtstreeks in je browser met NDJSON- en JSONL-bestanden. Alles wordt lokaal verwerkt, zodat je data privé blijft.
Ontdek hoe JSONL en NDJSON (Newline Delimited JSON) zich tot elkaar verhouden. Lees over de subtiele verschillen en wanneer je welke term gebruikt.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Leer hoe je JSONL-data in realtime streamt met Node.js, Python, Server-Sent Events en WebSockets. Bouw streamingpipelines voor logs, metrics en live datafeeds.
Lees wat JSONL (JSON Lines) is, hoe het verschilt van gewone JSON en waarom het zo vaak wordt gekozen voor het streamen van data, logbestanden en machinelearningdatasets.
Zet JSONL-bestanden om naar een standaard JSON-array. Ideaal voor API’s en dataverwerkingspipelines.