JSONL vs JSON: Differences, Examples and When to Use Each

Standard JSON has one top-level value

A standard JSON document contains exactly one top-level value. Multiple records are commonly represented as an array, and a normal parser generally treats that complete array as one document.

[
  {"id":1,"event":"created"},
  {"id":2,"event":"updated"}
]

JSONL stores one complete JSON value per line

JSON Lines, JSONL and NDJSON commonly refer to a line-delimited format where each non-empty line is parsed independently. The complete multi-line file is normally not one standard JSON value even though every record is valid JSON on its own.

{"id":1,"event":"created"}
{"id":2,"event":"updated"}

Why line-delimited data works well for logs and streams

A producer can append a new event without rewriting a closing array bracket. Consumers can process records as they arrive and can often report one malformed line without discarding every valid line after it.

• Append records naturally.
• Process large datasets incrementally.
• Report errors by line number.
• Split work on record boundaries.

When ordinary JSON is the better fit

Use standard JSON when the data is naturally one cohesive object, when a client expects application/json, or when relationships across the whole document matter. Configuration files and many REST responses fit this model well.

Do not pretty-print a JSONL record across lines

The usual JSONL convention is one complete value on each physical line. Pretty-printing a record across several lines breaks that record boundary. Pretty-print a selected record separately when you need to inspect it.

Blank-line handling and similar details can vary between libraries, so define pipeline behavior explicitly rather than assuming every implementation is identical.

Choose from the access pattern

Use JSON for cohesive documents and broad compatibility. Use JSONL when records are independent, appendable or too numerous to comfortably process as one in-memory array. The decision is about production and consumption patterns, not which syntax looks cleaner.

Think about failure recovery, not only file size

A malformed value near the end of one large JSON array can prevent a normal parser from producing the complete document. With line-delimited data, a consumer can often report the failing line while continuing with later independent records. That difference matters for logs, imports and event archives where partial progress is useful.

The trade-off is that JSONL gives up a single enclosing structure. Cross-record relationships, document-wide metadata and validations that depend on the complete collection may be clearer in standard JSON or in a format designed specifically for tabular or streaming data.