The structural difference
A normal JSON document must parse as one value from beginning to end. Multiple records are usually wrapped in an array. In JSONL, each line is parsed separately, so the file itself is not one valid JSON array.
JSON array
[
{ "id": 1, "event": "login" },
{ "id": 2, "event": "logout" }
]JSONL records
{"id":1,"event":"login"}
{"id":2,"event":"logout"}When JSON is the better format
Use JSON when the data is naturally one nested document or when consumers need the entire structure at once. Settings files, API request bodies, cached objects, and small exported datasets fit this model well.
- A single document can contain metadata beside its records.
- Arrays and nested objects can be formatted for humans without changing the format.
- Most browser and programming-language APIs parse JSON directly.
When JSONL is the better format
Use JSONL when records arrive over time or should be processed independently. A producer can append one line without reopening and rewriting an array, and a consumer can handle the file incrementally without loading every record into memory.
- Application logs and analytics events.
- Machine-learning training examples.
- Large exports consumed by command-line pipelines.
- Data streams where one malformed record should not hide every later record.
Validation and error recovery
One syntax error can invalidate an entire JSON document. In JSONL, each line has its own validation result, so a tool can report line 42 as invalid while still reading the surrounding records.
That independence is useful, but it also means a record must stay on one physical line. Do not pretty-print individual JSONL objects across multiple lines unless the receiving system explicitly supports a different framing protocol.
Converting between JSON and JSONL
To convert a JSON array to JSONL, serialize each array item as compact JSON and join the records with newline characters. To convert JSONL to JSON, parse every non-empty line and collect the results into an array.
Be careful with blank lines, line endings, and records that are valid primitive values rather than objects. JSONL permits any valid JSON value per line, although many data pipelines expect objects.