· 6 min read
If a tool rejects your file as invalid JSON and the file looks fine, it is often because the file is not one JSON document. It is many, one per line, which is a different format with a different name and a different parser.
A JSON file contains exactly one value, usually an array of objects. An NDJSON file contains one complete JSON value per line, with no enclosing array and no commas between lines. JSON Lines is the same thing under a different name, and the two labels are used interchangeably.
| 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. Pull out the line, paste it into a viewer to expand the tree, and validate it on its own. The tools here work on one document at a time and run in the browser, which matters because log lines routinely carry tokens and user identifiers.
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 file is NDJSON and 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.