Newline-Delimited JSON

{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Carol","role":"manager"}

Each line is a standalone JSON value that can be parsed independently. The newline character is the only delimiter. This simplicity is the format's entire purpose: any program that can read lines from a file can read NDJSON records.

Two names, one format

The NDJSON ecosystem carries a naming split that confuses developers encountering the format for the first time. Two independent specifications describe the same format:

JSON Lines (jsonlines.org, published 2013) uses the .jsonl extension and suggests the MIME type application/jsonl. NDJSON (GitHub ndjson-spec, published 2014) uses the .ndjson extension and specifies application/x-ndjson. A third historical name, LDJSON (Line Delimited JSON), appears in older documentation.

The rules are identical: UTF-8 encoding, one JSON value per line, newline separator. Both specs accept \n and \r\n as line endings. Both prohibit the byte-order mark (BOM). The communities behind the two specs have acknowledged the equivalence, yet the dual naming persists in tools, APIs, and file extensions. Elasticsearch uses application/x-ndjson. OpenAI's fine-tuning API accepts .jsonl files. MongoDB exports produce files that match both specs but use neither extension by default.

For practical purposes: .ndjson and .jsonl files are interchangeable. Rename one to the other and every compliant tool will process it identically.

Why newline-delimited: the streaming advantage

A standard JSON array wraps all records in brackets and separates them with commas:

[
  {"id":1,"name":"Alice"},
  {"id":2,"name":"Bob"}
]

To parse this, a program must either load the entire file into memory or implement a streaming JSON parser that tracks bracket nesting depth. For a 50 GB log file, both approaches carry substantial cost.

NDJSON eliminates the outer structure entirely. A consumer reads one line, parses it as JSON, processes it, discards it, and moves to the next line. Memory usage stays constant regardless of file size. A producer appends a new record by writing one line — no need to seek backward to insert before a closing bracket. This append-only property makes NDJSON the natural choice for log files, event streams, and data pipelines where records arrive continuously.

Unix command-line tools gain direct access to NDJSON records because the line is the record boundary: wc -l counts records, head -n 100 extracts the first hundred, tail -f streams new records as they arrive, and grep filters by content. None of these tools understand JSON — they understand lines, and NDJSON aligns its record boundary with the line boundary.

Format rules

The combined rules from both specifications:

1. Encoding: UTF-8, mandatory. No BOM.
2. Line content: Each line MUST contain exactly one valid JSON value per RFC 8259. Objects and arrays are most common, but strings, numbers, booleans, and null are permitted.
3. Line separator: \n (0x0A). \r\n (0x0D0A) is also accepted.
4. No embedded newlines: JSON string values must escape newlines as \n — a literal newline inside a JSON string would break line-based parsing.
5. Trailing newline: Recommended. Elasticsearch requires it. Many tools produce it. Omitting the final \n is tolerated by most parsers.
6. Empty lines: The NDJSON spec says parsers MAY silently ignore empty lines but MUST document this behavior. The JSON Lines spec does not address empty lines. In practice, most parsers skip them.
7. No outer structure: No opening bracket, no closing bracket, no trailing comma. The file is not valid JSON as a whole — only each individual line is.

Elasticsearch: the adoption catalyst

Elasticsearch's bulk API (_bulk and _msearch endpoints) requires NDJSON as its request body format. Every bulk indexing request sends alternating lines of action metadata and document source:

{"index":{"_index":"logs"}}
{"timestamp":"2026-04-03T10:00:00Z","level":"error","message":"disk full"}
{"index":{"_index":"logs"}}
{"timestamp":"2026-04-03T10:00:01Z","level":"info","message":"recovered"}

The Content-Type header must be application/x-ndjson (or application/json), and the final line must end with \n. Elasticsearch chose NDJSON because it needs to parse only the action line on the coordinating node to route the document to the correct shard — no full-body JSON parsing is required at the routing stage. This design decision, made before the format had widespread recognition, exposed millions of developers to NDJSON through the Elastic Stack (Elasticsearch, Logstash, Kibana). The ELK stack remains one of the largest sources of NDJSON traffic on the internet.

MongoDB, BigQuery, and the cloud ecosystem

MongoDB's mongoexport tool writes one JSON document per line by default — NDJSON format. mongoimport reads it back. Extended JSON encoding preserves BSON types (ObjectId, Date, Decimal128) that standard JSON cannot represent, but the line-per-document structure follows NDJSON rules exactly.

Google BigQuery accepts what it calls "newline-delimited JSON (ndJSON)" for data loading from Cloud Storage, and its documentation states explicitly that this is "the same format as the JSON Lines format." Each JSON object occupies one line; gzip-compressed files are limited to 4 GB and cannot be read in parallel (uncompressed files load faster because BigQuery parallelizes across file splits).

AWS services produce and consume NDJSON across the stack: CloudWatch Logs stores structured log entries as JSON objects, Kinesis Data Firehose delivers NDJSON to S3, and Athena queries NDJSON files with standard SQL. Apache Spark's spark.read.json() method reads NDJSON by default — standard JSON arrays require the explicit multiLine option.

MIME type and identification

NDJSON has no IANA-registered MIME type. The x- prefix in application/x-ndjson marks it as unregistered. Three MIME types circulate in practice:

• application/x-ndjson — used by Elasticsearch, most HTTP APIs, and the NDJSON spec
• application/jsonl — suggested by the JSON Lines spec, not widely adopted in HTTP headers
• application/json-seq — belongs to RFC 7464 (JSON Text Sequences), a different format that uses the ASCII Record Separator character (0x1E) as delimiter

Because NDJSON is plain text with no magic bytes, file identification relies entirely on the extension (.ndjson or .jsonl) or the Content-Type header. A file containing one JSON object per line but saved with a .json extension is ambiguous — tools cannot distinguish it from a standard JSON file without reading its contents.

Comparison with alternatives

NDJSON vs. JSON: A JSON array is a single valid document; NDJSON is a sequence of independent documents. JSON supports pretty-printing across lines; NDJSON requires each record on exactly one line. JSON is better for configuration files and API responses; NDJSON is better for logs, data feeds, and anything that grows over time.

NDJSON vs. CSV: CSV uses a fixed column header and stores flat tabular data. NDJSON supports nested objects, arrays, mixed types, and schema evolution (different fields on different lines). CSV is more compact for purely tabular data and universally supported by spreadsheet software. NDJSON preserves data types that CSV loses (numbers vs. strings, nulls vs. empty strings, nested structures).

NDJSON vs. Parquet: Parquet is a binary columnar format optimized for analytical queries — it compresses 5-10x better than NDJSON and supports predicate pushdown for fast column-specific reads. NDJSON is human-readable, append-friendly, and works with text tools. Parquet is better for data warehouse storage; NDJSON is better for data transit and logging.

Encoding and corruption

Both specifications require UTF-8. The most common corruption scenarios in NDJSON files:

• Broken JSON on a line: A truncated write (crash during append) leaves an incomplete JSON object on the last line. Parsers that skip invalid lines recover; strict parsers halt.
• Unescaped newlines in strings: A JSON string containing a literal newline instead of the escape sequence \n splits one record across two lines, breaking every downstream tool.
• BOM insertion: Some Windows editors insert a UTF-8 BOM (0xEF 0xBB 0xBF) at the start of the file. JSON parsers that do not strip BOM will fail on the first line.
• Mixed line endings: A file containing both \n and \r\n lines is valid per spec, but a poorly written parser that splits only on \n will leave trailing \r characters in parsed values.
• Trailing commas: Developers familiar with JSON arrays sometimes add commas at the end of NDJSON lines. These produce invalid JSON per RFC 8259.

Validation is straightforward: pipe the file through jq empty file.ndjson — jq exits with a non-zero status and prints the line number of the first invalid JSON value.