What is JSONL? Complete Guide to JSON Lines Format

Everything you need to know about JSON Lines — syntax, examples, use cases, and best practices.

Last updated: February 2026

What is JSONL?

JSONL (JSON Lines), also known as Newline Delimited JSON (NDJSON), is a text-based data format where each line is a valid JSON value, separated by newline characters. Unlike standard JSON, which wraps data in a single array or object, JSONL stores one record per line.

This simple design makes JSONL ideal for streaming, logging, and processing large datasets — each line can be read, parsed, and processed independently without loading the entire file into memory.

The format was popularized by tools and platforms that handle massive data volumes, including OpenAI (for fine-tuning datasets), BigQuery, Apache Spark, and log management systems.

JSONL Syntax Rules

The JSONL format follows a few simple rules:

  • Each line must be a valid JSON value (object, array, string, number, boolean, or null)
  • Lines are separated by newline characters (\n)
  • No commas or separators between lines
  • Files must use UTF-8 encoding
  • Trailing newline at end of file is optional
  • Empty lines are ignored by most parsers
Valid JSONL file
{"name":"Alice","age":30,"city":"New York"}
{"name":"Bob","age":25,"city":"London"}
{"name":"Charlie","age":35,"city":"Tokyo"}

Note: Each line is a complete, self-contained JSON object. There are no commas between lines and no wrapping array.

JSONL Examples

Simple Objects
{"id":1,"name":"Alice","email":"alice@example.com"}
{"id":2,"name":"Bob","email":"bob@example.com"}
{"id":3,"name":"Charlie","email":"charlie@example.com"}
Nested Objects
{"user":{"name":"Alice","age":30},"scores":[95,87,92]}
{"user":{"name":"Bob","age":25},"scores":[88,91,76]}
Mixed Types

JSONL lines don't all need to be the same type — each line just needs to be valid JSON:

{"event":"login","user":"alice","timestamp":"2026-01-15T10:30:00Z"}
{"event":"purchase","user":"alice","amount":29.99,"items":["book","pen"]}
{"event":"logout","user":"alice","timestamp":"2026-01-15T11:45:00Z"}
OpenAI Fine-Tuning FormatPopular

One of the most popular uses of JSONL is for OpenAI fine-tuning datasets:

{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is JSONL?"},{"role":"assistant","content":"JSONL is a text format where each line is a valid JSON value."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"How do I read a JSONL file?"},{"role":"assistant","content":"Read the file line by line, parsing each line as JSON."}]}

How to Read JSONL Files

JSONL files can be read with any tool that supports line-by-line text processing. Here are the most common methods:

Command Line

Use standard Unix tools to inspect JSONL files:

# View first 5 lines
head -n 5 data.jsonl

# Count total lines (records)
wc -l data.jsonl

# Pretty-print each line with jq
cat data.jsonl | jq .

# Filter by field value
cat data.jsonl | jq 'select(.age > 30)'
Python

Python's built-in json module handles JSONL naturally:

import json

with open('data.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line)
        print(record['name'])
JavaScript / Node.js

Read JSONL files line by line in Node.js:

import { createReadStream } from 'fs';
import { createInterface } from 'readline';

const rl = createInterface({
  input: createReadStream('data.jsonl')
});

for await (const line of rl) {
  const record = JSON.parse(line);
  console.log(record.name);
}

Online JSONL Viewer

For a visual approach, use jsonl.co to open and browse JSONL files up to 1GB — no uploads, everything runs in your browser.

How to Create JSONL Files

Creating JSONL files is straightforward — just write one JSON value per line.

Python
import json

records = [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25},
    {"name": "Charlie", "age": 35},
]

with open('output.jsonl', 'w') as f:
    for record in records:
        f.write(json.dumps(record) + '\n')
JavaScript / Node.js
import { writeFileSync } from 'fs';

const records = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 },
];

const jsonl = records
  .map(r => JSON.stringify(r))
  .join('\n');

writeFileSync('output.jsonl', jsonl + '\n');

Can You Add Comments in JSONL?

No. The JSONL specification does not support comments. Every line in a JSONL file must be a valid JSON value — and JSON itself has no comment syntax.

If you need to include metadata or annotations alongside your data, common workarounds include:

  • 1Add a metadata field to your JSON objects: {"_comment": "test data", "name": "Alice"}
  • 2Use a separate metadata file alongside your JSONL file
  • 3Add metadata as the first line of the file: {"_meta": {"version": "1.0", "created": "2026-01-15"}}

Keep in mind that any "comment" fields will be parsed as regular data. Applications consuming the JSONL file should be designed to ignore metadata fields.

JSONL vs JSON

The key difference is structure. JSON wraps everything in a single value, while JSONL stores one value per line.

JSONStandard JSON
[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25}
]
JSONLJSONL (JSON Lines)
{"name":"Alice","age":30}
{"name":"Bob","age":25}
  • JSON must be fully loaded into memory to parse; JSONL can be read line by line
  • JSON needs commas between elements; JSONL uses newlines
  • JSON is better for config files and APIs; JSONL is better for large datasets and streaming
  • Appending to JSON requires rewriting the entire file; JSONL just appends a new line

For a detailed comparison, see our complete JSON vs JSONL guide.

Common Use Cases

Machine Learning & AI

Most Popular

JSONL is the standard format for ML training data. OpenAI, Hugging Face, and other AI platforms use JSONL for fine-tuning datasets because each training example is a self-contained line that can be shuffled, sampled, and streamed efficiently.

Log Files & Event Streams

JSONL

Structured logging systems (ELK stack, Datadog, CloudWatch) output logs in JSONL format. Each log entry is one JSON line, making it easy to append new entries and process logs in real time.

Big Data Processing

JSONL

Tools like Apache Spark, BigQuery, and AWS Athena natively support JSONL. The line-by-line format allows parallel processing across distributed systems — each worker can process a chunk of lines independently.

Streaming APIs

JSONL

APIs that return large result sets often use JSONL streaming. The client can start processing results immediately as they arrive, without waiting for the complete response.

JSONL File Extensions

JSONL files commonly use these extensions:

.jsonlThe standard JSONL extension, most widely used
.ndjsonNewline Delimited JSON — technically the same format with a different name
.jsonSome tools output JSONL with a .json extension, which can cause confusion

All three extensions contain the same format — one JSON value per line. The MIME type for JSONL is application/jsonl or application/x-ndjson.

Try Our JSONL Viewer

Open, view, and edit JSONL files up to 1GB — right in your browser. No uploads, 100% private.

Frequently Asked Questions

What is JSONL? Complete Guide to JSON Lines Format