JSON Lines (JSONL) Explained: Format, Uses and Common Errors

JSON Lines — also called JSONL, or NDJSON for newline-delimited JSON — is a simple variation of JSON: instead of one big document, a file contains one complete JSON value per line. That small change makes it one of the most practical formats for large datasets, logs and machine-learning training data.

The format in one example

events.jsonl

{"ts": "2026-11-10T08:00:01Z", "level": "info", "msg": "server started"}
{"ts": "2026-11-10T08:00:07Z", "level": "warn", "msg": "slow query", "ms": 812}
{"ts": "2026-11-10T08:01:12Z", "level": "error", "msg": "db timeout"}

The rules are short: the file is UTF-8 text, each line is a valid JSON value (almost always an object), and lines are separated by a newline character. There are no commas between records and no surrounding square brackets. The same data as a regular JSON array would be wrapped in [ … ] with commas between the objects.

Why not just use a JSON array?

• Streaming: a program can read and process one line at a time without loading the whole file into memory. A JSON array has to be parsed completely — or with a special streaming parser — before you can use it.
• Appending: adding a record means writing one more line. With an array you must rewrite the closing bracket and insert a comma, which is fragile when several processes write to the same file.
• Splitting and sampling: standard tools such as head, tail, split, wc -l and grep work directly on JSONL, because one line is one record.
• Error isolation: one corrupted line does not make the entire file unreadable; you can skip or fix that line alone.

The trade-off is readability: records cannot be pretty-printed across several lines, so a JSONL file is harder for humans to scan. Converting it to a formatted array with the JSONL to JSON converter makes inspection easy.

Where JSONL is used

• Logging — structured application logs are commonly written as one JSON object per line.
• Data warehouses — Google BigQuery imports and exports newline-delimited JSON.
• Search engines — the Elasticsearch and OpenSearch bulk APIs use NDJSON bodies.
• AI datasets — many machine-learning datasets, including those on Hugging Face, are distributed as JSONL, and LLM fine-tuning services typically expect one training example per line.

JSONL for fine-tuning datasets

For chat-model fine-tuning, a common structure is one object per line containing a messages array of role/content pairs:

train.jsonl

{"messages": [{"role": "system", "content": "You answer in one short sentence."}, {"role": "user", "content": "What is the capital of Morocco?"}, {"role": "assistant", "content": "Rabat is the capital of Morocco."}]}
{"messages": [{"role": "system", "content": "You answer in one short sentence."}, {"role": "user", "content": "Translate 'thank you' into French."}, {"role": "assistant", "content": "Merci."}]}

Each provider documents its own required fields, so always check the current specification before uploading. A practical workflow is to build and edit your examples as a regular, pretty-printed JSON array — or even in a spreadsheet — and convert to JSONL at the end with the JSON to JSONL converter.

The most common JSONL errors

• Pretty-printed records. An object spread over several lines breaks the one-record-per-line rule. Each record must be serialised compactly on a single line.
• Literal line breaks inside strings. A newline inside a value must be written as the escape \n. A real line break splits the record in two invalid halves.
• Commas or brackets left over from an array. Lines ending in }, or a file starting with [ mean an array was only partly converted.
• A truncated last line. If a process crashed while writing, the final line may be incomplete JSON.
• Wrong encoding or a BOM. JSONL should be UTF-8. A byte-order mark at the start can make the first line fail in strict parsers.
• Single quotes or trailing commas. Each line must be strict JSON — Python's str(dict) output, for example, is not valid JSON.

The JSONL to JSON converter parses the file line by line and reports the exact line number of the first invalid record, which is the quickest way to find these mistakes in a large file.

Reading and writing JSONL in code

Python

import json

# Read
with open("data.jsonl", encoding="utf-8") as f:
    records = [json.loads(line) for line in f if line.strip()]

# Write
with open("out.jsonl", "w", encoding="utf-8") as f:
    for r in records:
        f.write(json.dumps(r, ensure_ascii=False) + "\n")

Command line (jq)

jq -c '.[]' data.json > data.jsonl      # JSON array -> JSONL
jq -s '.' data.jsonl > data.json        # JSONL -> JSON array

Summary

JSON Lines is JSON with one record per line. It is ideal for logs, large datasets and AI training files because it can be streamed, appended to and split easily. Keep every record on a single line, escape line breaks inside strings, use UTF-8, and validate the file line by line before uploading it anywhere.

Frequently asked questions

More guides

• Why Your CSV Opens in One Column in Excel (and How to Fix It)
• How to Keep Leading Zeros (and Long Numbers) When Opening CSV in Excel
• Fix Garbled Characters (é, è, ????) in CSV Files Opened in Excel
• How to Flatten Nested JSON into a CSV Table