JSON vs NDJSON: Logs, Streaming, and Line-Delimited Data

Q: What is NDJSON (Newline Delimited JSON)?

NDJSON stands for Newline Delimited JSON. It is a format where each line in a file or stream is an independent, complete JSON value — typically a JSON object. Each line is separated by a newline character (\n). Unlike a standard JSON array, NDJSON files do not have a wrapping array or commas between records, so each line can be parsed independently using JSON.parse(line) without loading the entire file. NDJSON is also called JSON Lines (.jsonl) or LDJSON. It is widely used for log files, analytics event streams, database exports, and any workload that processes records one at a time.

Q: Can I stream NDJSON but not JSON?

NDJSON is naturally stream-friendly because each newline-terminated line is a self-contained record. A reader can process each line as it arrives without waiting for the full file, which is ideal for large exports, real-time log streams, and batch processing pipelines. Standard JSON requires the entire document to be received before parsing begins, because the parser cannot know when an array is complete until the closing bracket arrives. Streaming parsers for JSON exist (such as JSONStream for Node.js or ijson for Python) that handle JSON arrays progressively, but they are more complex to use than simple NDJSON line splitting.

Q: What is the difference between JSON Lines and NDJSON?

JSON Lines (file extension .jsonl) and NDJSON are effectively the same format with different names. Both store one valid JSON value per line, separated by newlines. LDJSON (Line Delimited JSON) is a third name for the same concept. The slight differences: NDJSON specifies that each line should be a complete JSON value and may allow an optional trailing newline at the end of the file. JSON Lines specifies the same but is the more commonly used name in the data engineering community. In practice, files produced by one name are fully compatible with parsers expecting the other, and the terms are used interchangeably.

Q: Which is better for log files: JSON or NDJSON?

NDJSON is significantly better for log files than standard JSON arrays. With NDJSON, each log event is a complete line that can be appended independently — no array bracket or comma editing is needed when writing new events. If the application crashes mid-write, only the incomplete line at the end is corrupted; all previous lines are valid. With a JSON array, appending a new entry requires editing the closing bracket and adding a comma, which is not safe for concurrent writes. Tools like jq, grep, awk, and most log aggregators (Fluentd, Logstash, Vector) natively handle NDJSON line-by-line without loading the whole file.

Q: Can a standard JSON parser read NDJSON directly?

A standard JSON parser cannot parse a multi-line NDJSON file as a whole because the file is not valid JSON — it contains multiple root values without an array wrapper. However, you can parse NDJSON by splitting the content on newlines and calling JSON.parse on each non-empty line individually. In JavaScript: const records = text.split("\n").filter(Boolean).map(JSON.parse). In Python: [json.loads(line) for line in file if line.strip()]. This is the standard pattern for reading NDJSON. Libraries like ndjson (Node.js), jsonlines (Python), and jq (command line) also handle NDJSON files directly.

Q: When does NDJSON break?

NDJSON breaks when a JSON value itself contains unescaped newline characters. Since lines are delimited by newlines, a string value with a literal newline (\n) inside would cause the parser to treat it as two separate lines, both of which may be invalid JSON fragments. The fix is to ensure all string values with newlines use the JSON escape sequence \n rather than a literal newline character — proper JSON serializers do this automatically. NDJSON also breaks if any line is an empty string that is not filtered out before parsing, or if a writer adds a byte-order mark (BOM) to the start of the file that confuses the JSON parser.

Last updated: May 11, 2026

NDJSON (Newline-Delimited JSON) stores 1 complete JSON value per line, separated by \n, while standard JSON is a single document — that single structural rule determines which format to use. NDJSON lets you process a 10 GB log file in under 100 MB of RAM by reading line-by-line; standard JSON requires loading the entire document before the first record can be read, which fails past ~1 GB on most servers. NDJSON has 3 common names: NDJSON, JSON Lines (.jsonl), and LDJSON — all are wire-compatible. This guide covers the syntax difference between the 2 formats, streaming NDJSON in Node.js and Python, appending to log files safely, jq and command-line processing, and a decision checklist for choosing between them.

Example difference

[
  { "event": "login", "userId": 1 },
  { "event": "logout", "userId": 1 }
]

{ "event": "login", "userId": 1 }
{ "event": "logout", "userId": 1 }

The first block is one JSON array. The second block is NDJSON: each line can be parsed independently with JSON.parse(line).

Quick comparison

Feature	JSON	NDJSON
Document shape	One value, often an object or array	One JSON value per line
Append new record	Requires editing the whole array	Append a line
Stream processing	Needs full document or streaming parser	Natural line-by-line parsing
Validation	Validate the whole document	Validate each line as a record
Best fit	APIs, config, structured files	Logs, exports, queues, analytics events

When to use JSON

API responses that return one coherent resource or collection.
Config files where the entire document is loaded together.
Nested data that belongs to one top-level object.
Browser tools where users expect a single valid JSON document.

When to use NDJSON

Application logs where each event is independent.
Large exports that should be processed without loading everything into memory.
Streaming APIs that send records as they become available.
Batch imports where one bad record should not discard the whole file.

Parsing pattern

For NDJSON, split on newlines and parse each non-empty line. For a normal JSON array, parse once and then iterate over the array.

const records = ndjson
  .split('\n')
  .filter(Boolean)
  .map((line) => JSON.parse(line))

If parsing fails, the line number tells you which record is malformed. See the JSON.parse error guide for common syntax failures.

Validate sample records

Paste one NDJSON line or a converted JSON array into Jsonic's JSON Formatter to check syntax before writing an import or streaming parser.

Open JSON Formatter

Frequently asked questions

What is NDJSON (Newline Delimited JSON)?

NDJSON stores one complete JSON value per line, separated by newlines. Each line can be parsed independently with JSON.parse. Also called JSON Lines (.jsonl) or LDJSON. It is used for logs, analytics events, and database exports that process records one at a time.

Can I stream NDJSON but not JSON?

Yes. NDJSON lines are self-contained, so a reader processes each as it arrives. Standard JSON requires the full document before parsing. Streaming JSON parsers exist (JSONStream, ijson) but are more complex than simple NDJSON line splitting.

What is the difference between JSON Lines and NDJSON?

JSON Lines (.jsonl) and NDJSON are the same format with different names. LDJSON is a third name. All store one JSON value per line. Files produced under any name are fully compatible with parsers expecting any other name.

Which is better for log files: JSON or NDJSON?

NDJSON is much better. Append a new log event by adding a line — no array bracket or comma editing needed. If the app crashes mid-write, only the last incomplete line is corrupted. Tools like jq, Logstash, and Vector read NDJSON line-by-line natively.

Can a standard JSON parser read NDJSON directly?

Not as a whole file — multi-line NDJSON is not valid JSON. Split on newlines and call JSON.parse per line: text.split("\n").filter(Boolean).map(JSON.parse). Libraries like jsonlines (Python) and jq also handle NDJSON files directly.

When does NDJSON break?

NDJSON breaks if a string value contains a literal unescaped newline character, since that splits one value across two lines. Proper JSON serializers always escape newlines as \n. Also filter empty lines before parsing and avoid byte-order marks at the file start.