JSONL and NDJSON Explained: One JSON Object Per Line

What is JSONL?

JSONL (JSON Lines) is a text format where each line contains exactly one complete, valid JSON value — almost always an object — and lines are separated by newline characters. There are no commas between records and no surrounding square brackets. A three-record JSONL file is literally three lines, each independently parseable.

That structure makes JSONL append-friendly and streamable: to add a record you write one more line, and to read a file you process it line by line without ever loading the whole thing into memory.

{"id": 1, "name": "Ada"}
{"id": 2, "name": "Linus"}
{"id": 3, "name": "Grace"}

JSONL versus a JSON array

A JSON array is a single document: every element is comma-separated and wrapped in brackets, and a parser must read the entire array before it can hand you the first item. For a 10 GB file, that means 10 GB of RAM and a long wait before any work begins.

JSONL flips this. Because each line stands alone, you can stream a massive file one record at a time, process it on commodity hardware, and parallelize across workers — each line is an independent unit. The trade-off is that JSONL is not itself valid JSON, so tools that expect a single document need a conversion step first.

[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Linus"},
  {"id": 3, "name": "Grace"}
]

JSONL, NDJSON, and JSON Lines — what is the difference?

In practice, none. JSON Lines (jsonlines.org) and NDJSON, Newline Delimited JSON (ndjson.org), have slightly different formal specifications, but both describe the same thing: one JSON value per line, newline-separated, UTF-8 encoded. You can treat JSONL and NDJSON as interchangeable names for the same format, and the .jsonl and .ndjson extensions both refer to it.

Where JSONL is used

• Machine learning and LLM training — OpenAI fine-tuning, Google Vertex AI, and HuggingFace datasets all distribute data as JSONL, with one training example per line so datasets stream without loading entirely into memory.
• Structured logging — systems like the ELK stack, Datadog, and CloudWatch emit one JSON log entry per line, which is trivial to append in real time and to tail.
• Data warehouses and big data — BigQuery, AWS Athena, and Apache Spark natively ingest newline-delimited JSON, and the line format enables parallel processing across distributed workers.
• Bulk and streaming APIs — endpoints that return large result sets stream them as JSONL so clients can begin processing before the response finishes.

JSONL rules and common gotchas

• Exactly one JSON value per line — usually an object, but any valid JSON value is allowed.
• Newline-separated, not comma-separated, and with no wrapping brackets.
• UTF-8 encoding is expected; each line should be independently parseable.
• A trailing newline at the end of the file is fine and common — blank lines are simply skipped by good parsers.
• Do not pretty-print: each record must stay on a single line, because the newline is the record delimiter.

Converting between JSONL and JSON

Most application code expects an array, so the common task is wrapping JSONL into a single JSON array — reading each line, parsing it, and collecting the results into [ ... ]. The reverse, splitting a JSON array into one object per line, is what you do before loading data into a streaming system or a fine-tuning pipeline.

You can do both conversions instantly with the JSONL to JSON and JSON to JSONL tools, which run in your browser. To catch a malformed record before it breaks a pipeline, validate the file first with a JSONL validator that reports the exact line that failed.

Working with JSONL in code

On the command line, wc -l counts records instantly because each line is one record, and jq with the -c flag emits compact JSONL. In Python, pandas reads it with read_json(path, lines=True), and you can loop over a file object parsing one line at a time. In Node.js, a readline stream lets you handle each record without buffering the whole file. The unifying idea is the same everywhere: treat the file as a stream of lines, not as one document.

wc -l data.jsonl       # count records (one per line)
jq -c '.[]' data.json  # JSON array → JSONL

import pandas as pd
df = pd.read_json("data.jsonl", lines=True)