Tablizer

JSON vs JSON Lines: When to Use Each

Last updated 19 August 2026 · about 4 minutes to read

JSON wraps records in an array. JSON Lines puts one per line with no wrapper. What that changes for streaming, appending and failure handling.

JSON Lines is not a variant of JSON, it is a file format built out of JSON. Each line is a complete JSON value. The file as a whole is not valid JSON, and that is the entire point.

The same three records, both ways
// JSON: one document
[
  { "id": 1, "event": "start" },
  { "id": 2, "event": "stop" },
  { "id": 3, "event": "start" }
]

// JSON Lines: three documents in one file
{"id":1,"event":"start"}
{"id":2,"event":"stop"}
{"id":3,"event":"start"}

What the wrapper costs

A JSON array is a single value, so a parser has to reach the closing bracket before it can hand you anything. For a two-gigabyte file that means holding two gigabytes in memory before the first record is available.

Appending has the same problem in reverse. Adding a record to a JSON array means rewriting the end of the file, because the closing bracket has to move. With JSON Lines you open the file in append mode and write a line, which is an operation the filesystem does atomically for small writes.

Failure handling differs too. One malformed record in a JSON array makes the whole document unparseable. One malformed line in a JSON Lines file makes that line unparseable and leaves the rest readable.

When to use which

Use JSON when

  • The data is a document rather than a sequence: a configuration file, an API response, a saved state.
  • The consumer wants the whole thing anyway.
  • It has to be readable by something that only speaks JSON, which is most things.
  • The structure is not a list of similar records at all.

Use JSON Lines when

  • Records arrive over time: logs, events, telemetry, audit trails.
  • The file is large enough that loading it whole is a problem.
  • Something needs to process it record by record, which is how most data pipelines and machine learning loaders work.
  • Partial reads have to be useful, meaning a truncated file should still yield the records that made it.

Practical notes

The extension is .jsonl. You will also see .ndjson, for newline-delimited JSON, which is the same thing under a different name. Both are read the same way.

There is no comma between records and no trailing comma anywhere. A line ends with the closing brace and then a newline. Getting that wrong is the most common mistake when writing JSON Lines by hand.

Standard command line tools work on it in a way they do not on JSON. wc -l counts records. head gives you the first ten. grep finds the ones you want. split cuts it into pieces that are each still valid. None of those work on a JSON array, which is a large part of why the format exists.

Tools mentioned here

Questions

Can a JSON Lines file be pretty-printed?

No. Each record has to be on exactly one line, so indentation is not available. If you want to read one record, extract that line and format it on its own.

How do I convert between them?

Both directions are one step. JSON to JSON Lines drops the array wrapper and writes each element on its own line. JSON Lines to JSON collects the lines into an array. Both are on this site.

More guides