JSON vs. NDJSON – Definition and Differences
Compare a single JSON document with newline-delimited records on streaming, appending, failure isolation, and when each is correct.
NDJSON — newline-delimited JSON, also called JSON Lines — puts one complete JSON value per line. Plain JSON puts the whole dataset in one document. The difference decides how a file can be produced and consumed.
1. The Two Shapes
[
{"id": 1, "title": "Widget"},
{"id": 2, "title": "Gadget"}
]
{"id": 1, "title": "Widget"}
{"id": 2, "title": "Gadget"}
The second has no enclosing array and no commas between records.
2. Key Differences
| Dimension | JSON document | NDJSON |
|---|---|---|
| Parse granularity | The whole file | One line |
| Memory to read | Proportional to file size | Proportional to one record |
| Appendable | No — the closing bracket blocks it | Yes |
| Splittable | No | Anywhere on a line boundary |
| One malformed record | Invalidates the file | Affects that line only |
| Partial file | Invalid | Valid up to the last complete line |
| Command-line tooling | Needs a JSON parser | Line tools work directly |
3. Why Appendability Matters for Collection
A collector writes records as it finds them. With NDJSON that is a line append. With a JSON array it means either holding everything in memory until the end or rewriting the closing bracket.
The consequence is also about failure: an interrupted NDJSON file is valid up to its last complete line, while an interrupted JSON array is unparseable.
4. Failure Isolation
One record containing invalid JSON — an unescaped character in a description, say — breaks an entire JSON document. In NDJSON it breaks one line, and the rest processes.
At scale that difference determines whether a batch is salvageable.
5. Where a Single Document Is Correct
- Configuration, which is one object rather than a series.
- API responses, where consumers expect a document.
- Nested structures that are not a list of like records.
- Small datasets handed to a person who will open them.
NDJSON is for sequences of records. Using it for a single configuration object is as wrong as using an array for a streaming log.
6. Conventions Worth Following
Use the .jsonl or .ndjson extension, write UTF-8 without a byte order mark, keep one record type per file, avoid literal newlines inside string values, and include an identifier and a collection timestamp in every record.
Gzip compresses it well and remains streamable, so a compressed file can still be read line by line.
7. Where Both Give Way to Parquet
Once data is settled and queried analytically, a columnar format is smaller, typed, and far faster to filter.
The common progression is NDJSON as the collection format, Parquet as the stored format, and CSV as the export for people.
8. Summary
A JSON document holds the whole dataset and must be parsed as a unit; NDJSON holds one record per line and can be streamed, appended, split, and partially recovered.
Use NDJSON for sequences of records and a single document for configuration and API payloads — and move to Parquet once the data is being analysed rather than collected.