· Updated · 6 min read
The difference between NDJSON and JSON is the unit of the file. A JSON file is one value, usually an array of objects wrapped in brackets with commas between items. An NDJSON file (newline-delimited JSON, also called JSON Lines) is one complete JSON value per line, with no wrapping array and no commas between lines, so it can be read, appended to and recovered line by line.
TL;DR: use JSON for one document you read whole, such as a config or an API response. Use NDJSON for records that are streamed, appended or processed one at a time, such as logs and exports. NDJSON and JSON Lines are the same format under two names.
NDJSON stands for newline-delimited JSON. Each line is a valid JSON value on its own (in practice, an object), lines are separated by a newline character, and the file as a whole is not valid JSON. A minimal example with three records:
{"id":1,"name":"Ada"}
{"id":2,"name":"Grace"}
{"id":3,"name":"Linus"}The same data as a JSON file is a single array: [{"id":1,"name":"Ada"},{"id":2,"name":"Grace"},{"id":3,"name":"Linus"}]. The two formats are specified at the ndjson-spec repository and jsonlines.org, which describe the same rules: UTF-8, one value per line, a newline between records.
| JSON | NDJSON / JSON Lines | |
|---|---|---|
| Top level | One value for the whole file | One value per line |
| Commas between records | Yes | No |
| Wrapping brackets | Yes | No |
| Must read whole file to parse | Yes | No, line by line |
| Can append safely | No, the closing bracket is in the way | Yes, just add a line |
| Survives truncation | No, the whole file fails | Yes, you lose the last line |
Three properties make it the default for anything streamed. You can append a record by writing a line, without rewriting the end of the file. You can parse it with constant memory, one line at a time, no matter how large the file is. And if the process dies mid-write, you lose one line rather than the whole document.
A standard JSON array has none of these. Appending means seeking back over the closing bracket, parsing means reading the whole thing, and a truncated file is entirely unparseable.
A file with a .json extension can perfectly well contain NDJSON. The extension is a convention and nothing enforces it, which is exactly how this confusion starts.
Going from NDJSON to JSON means wrapping the lines in brackets and putting commas between them. Going the other way means taking each element of the top-level array and writing it on its own line. Both are mechanical, and both fail in the same place: a record that is itself pretty-printed across several lines is not valid NDJSON, because NDJSON requires each record to occupy exactly one line.
When you are debugging NDJSON, you are usually looking at one line at a time. AstralJSON has no NDJSON mode: its tools take one JSON document at a time. So pull out one line and paste it into the viewer to expand the tree, or into the validator to check it on its own. Both run in the browser, which matters because log lines routinely carry tokens and user identifiers.
Try it or go deeper
JSON is one value for the whole file, usually an array with commas and brackets. NDJSON is one complete JSON value per line, with no wrapping array and no commas, so it can be streamed, appended to and read line by line.
No. The two names describe the same format: one complete JSON value per line, no commas, no wrapping array. You will see both labels used for the same files.
Most likely the parser expects a single JSON document. Feed it one line at a time, or wrap the lines in an array with commas.
Not in place. Pretty-printing spreads a record over several lines, which breaks the one record per line rule. Expand a single line when you need to read it, and keep the stored file compact.
Not as a format. Its tools take one JSON document at a time, so paste a single NDJSON line to view or validate it. Everything runs in your browser tab.