What is NDJSON?

Newline-Delimited JSON · reference docs · updated 22 May 2026 · vs JSONL · spec · validator · normalizer

NDJSON — Newline-Delimited JSON — is a streaming text format where each line is one independent, valid JSON value, separated by \n. There is no enclosing array, no comma between records, no surrounding document. NDJSON is the same format as JSON Lines (JSONL); the two names are interchangeable. NDJSON is the spelling preferred in the JavaScript / Node ecosystem and pushed by ndjson.org; JSONL is the spelling preferred in Python, ML, and data engineering.

The shape

{"id":1,"event":"signup","ts":"2026-05-22T08:14:01Z"}
{"id":2,"event":"click","ts":"2026-05-22T08:14:03Z","path":"/pricing"}
{"id":3,"event":"checkout","ts":"2026-05-22T08:14:11Z","amount":29}

Each line is parseable on its own with JSON.parse (or any RFC 8259 parser). The file as a whole is not a single JSON document — you must split on \n first and then parse each line. This is the entire format. There is no header, no schema, no metadata.

Quick facts

Why NDJSON exists

Regular JSON is a single document. To send a sequence of records, you have to either:

• Wrap them in a JSON array ([record, record, record]) — which means the consumer cannot read record 1 until the whole array has arrived, and you cannot append a record without rewriting the file.
• Send them framed somehow — which is what NDJSON does, using the simplest possible framing: one record per line.

NDJSON solves the streaming problem with one rule change: delete the array brackets and the commas, separate records with newlines. Everything else falls out of that: you can stream, append, tail, grep, and split the file with normal Unix tooling, and one corrupt record doesn't poison the rest.

Where NDJSON is used

• HTTP streaming responses. When an API returns many records and you want the client to start processing immediately, NDJSON with Content-Type: application/x-ndjson and chunked transfer encoding is the canonical pattern. OpenAI and Anthropic streaming completions use this shape.
• Structured application logs. Node's pino, Go's slog, Python's structlog, Java's logback JSON encoder — all emit one JSON object per line.
• Observability pipelines. Datadog, Loggly, New Relic, Vector, Fluentbit, Logstash all natively ingest NDJSON.
• Search ingest. Elasticsearch and OpenSearch's _bulk API consumes NDJSON for batch indexing.
• D3 / data viz. The npm ndjson family of streaming parsers is part of Mike Bostock's data-viz toolchain.
• Server-Sent Events alternatives. NDJSON-over-HTTP is a popular alternative to SSE for streaming structured data to browsers.
• ML inference batching. Many model-serving runtimes accept NDJSON for batched-prediction requests.

NDJSON rules

1. One JSON value per line.
2. Lines separated by \n (LF).
3. Each line, in isolation, is valid JSON per RFC 8259.
4. UTF-8 encoded, without BOM.
5. No comments, no trailing commas, no NaN / Infinity (same as JSON).
6. Blank lines are not in the spec; most parsers tolerate them, strict parsers reject.
7. Trailing \n after the last record is recommended but not required.

That's the entire specification. For the formal rules and the edge cases parsers disagree on — these apply to NDJSON identically — see the JSONL specification.

NDJSON vs JSONL — the relationship

NDJSON and JSONL are the same format. The difference is purely the name and which ecosystem promotes it:

• NDJSON — promoted by ndjson.org. Dominant in JavaScript, Node, observability, and HTTP streaming.
• JSONL — promoted by jsonlines.org. Dominant in Python, data engineering, and ML training pipelines (HuggingFace, OpenAI fine-tunes).
• LDJSON — historical synonym, now rare.

If you receive an .ndjson file and your tool expects .jsonl (or vice versa), just rename it — the content is identical. Use the NDJSON ↔ JSONL normalizer if you also need to strip a BOM or normalize line endings in the same pass. For a deeper side-by-side, see NDJSON vs JSONL.

NDJSON over HTTP

The canonical streaming pattern:

HTTP/1.1 200 OK
Content-Type: application/x-ndjson
Transfer-Encoding: chunked

{"id":1,"event":"signup"}
{"id":2,"event":"click"}
{"id":3,"event":"checkout"}

Each chunk ends at a \n boundary so the client can parse complete records as bytes arrive. Producers should flush after each record (or every N records). Consumers should accumulate bytes until the next \n, then parse and emit.

Minimal Node consumer:

const res = await fetch(url);
const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += dec.decode(value, { stream: true });
  let i;
  while ((i = buf.indexOf('\n')) >= 0) {
    const line = buf.slice(0, i).trim();
    buf = buf.slice(i + 1);
    if (line) handle(JSON.parse(line));
  }
}

NDJSON gotchas

• BOM at the start. Some Windows producers emit EF BB BF before the first record. Many parsers treat it as part of the first line, breaking the record. Strip on read; never emit.
• CRLF line endings. Tolerated by most parsers but not strictly NDJSON. Normalize to LF for portability.
• Multi-line JSON. Pretty-printed JSON spanning several lines is not NDJSON. Minify each record first.
• Embedded newlines in strings. Must be escaped as \n inside the JSON value, never raw.
• Heterogeneous shapes. Allowed by the spec, but most consumers assume one schema per file. Stick to it.
• Mistaking NDJSON for JSON. If you JSON.parse a whole NDJSON file, you'll get a parse error on the first newline. Split first.

NDJSON in three languages

Node (streaming):

const { createReadStream } = require('fs');
const readline = require('readline');
const rl = readline.createInterface({ input: createReadStream('events.ndjson') });
rl.on('line', l => { if (l.trim()) handle(JSON.parse(l)); });

Python (streaming):

import json
with open('events.ndjson', encoding='utf-8') as f:
    for line in f:
        line = line.strip()
        if line:
            handle(json.loads(line))

Go (streaming):

scanner := bufio.NewScanner(f)
scanner.Buffer(make([]byte, 64*1024), 16*1024*1024)
for scanner.Scan() {
    var r Record
    if err := json.Unmarshal(scanner.Bytes(), &r); err == nil {
        handle(r)
    }
}

Tools on this site that work on NDJSON

1. NDJSON Validator — per-line syntax check.
2. NDJSON ↔ JSONL — strip BOM, normalize CRLF, drop blank lines, download with either extension.
3. Viewer — record-by-record tree / grid view.
4. Auto-fixer — repair trailing commas, single quotes, smart quotes, comments.
5. Formatter — pretty-print or minify each record individually.
6. Query (jq-style) — slice, filter, reshape with jq syntax.
7. NDJSON → CSV — flatten nested keys and download a spreadsheet-ready file.

All tools accept both .ndjson and .jsonl; the file picker explicitly allows both extensions.

FAQ

— S., [email protected]