JSON vs JSONL: differences and when to use each
JSON holds one document per file; JSONL (newline-delimited JSON) holds one JSON object per line. Same syntax per value, opposite trade-offs for streaming, logs, and large datasets.
A JSONL file is simply valid JSON values separated by newlines, with no enclosing array and no commas between lines. Each line parses independently, which changes everything about how the file can be produced and consumed.
Same data, both formats
json
// JSON: one array document
[
{ "id": 1, "ok": true },
{ "id": 2, "ok": false }
]jsonl
// JSONL: one object per line
{ "id": 1, "ok": true }
{ "id": 2, "ok": false }Head-to-head
| JSON | JSONL | |
|---|---|---|
| Structure | One value per file | One value per line |
| Streaming writes | Hard: needs the closing bracket | Trivial: append a line |
| Streaming reads | Needs an incremental parser | Read line by line |
| Partial corruption | Whole file fails | Only bad lines fail |
| Human editing | Formatter-friendly | Grep and sed friendly |
| Typical use | APIs, configs | Logs, datasets, exports |
When to pick each
- Pick JSON for API payloads, config files, and anything a human edits by hand.
- Pick JSONL for append-only logs, event streams, and datasets too big to hold in memory.
- Pick JSONL when producers and consumers are decoupled: writers never need to know the total.
Converting between them
JSONL to JSON: wrap the lines in [ ], join with commas. JSON array to JSONL: print each element on its own line. jq does both in one command: jq -c '.[]' array.json produces JSONL, and jq -s '.' lines.jsonl collects it back.
Note that jsonblocks tools expect standard JSON. To inspect JSONL here, convert it to an array first, or validate one line at a time.
Frequently asked questions
What does JSONL stand for?
JSON Lines, also called newline-delimited JSON (NDJSON). Each line is a self-contained JSON value, usually an object.
Is JSONL valid JSON?
No. A multi-line JSONL file is not one JSON document, so JSON.parse rejects it. Parse line by line instead, or wrap the lines into an array.
Why do logs use JSONL?
Writers can append one line per event without reading or rewriting the file, and readers can stream it line by line. A corrupt line costs one event, not the whole file.