Official specification and technical standards for JSON Lines format
JSON Lines (JSONL), also known as Newline Delimited JSON (NDJSON), is a text format for storing structured data.
Each line consists of a valid JSON value, separated by the newline character \n (Line Feed, U+000A).
The format is designed for convenient storage and processing of structured data that may be processed one record at a time, making it ideal for streaming, logging, and append-only data scenarios.
A JSONL file as a whole is not a valid JSON document. You cannot wrap the entire file in [ and ] and parse it as a JSON array.
// This is NOT valid JSON:
{"id": 1}
{"id": 2}
{"id": 3}Unlike items in a JSON array, there are no commas separating the JSON objects on each line.
// JSONL - NO COMMAS:
{"name": "Alice"}
{"name": "Bob"}
// JSON Array - COMMAS REQUIRED:
[
{"name": "Alice"},
{"name": "Bob"}
]The entire collection of objects is not wrapped in an outer array ([ and ]). Each line stands alone.
Unlike CSV, each line is a full JSON object, so it perfectly supports nested objects, arrays, and all JSON data types.
{"user": "alice", "tags": ["admin", "dev"], "meta": {"role": "lead"}}
{"user": "bob", "tags": ["user"], "meta": {"role": "member"}}Each line must be a valid JSON value. The most common type is a JSON object, but arrays, strings, numbers, booleans, and null are also valid.
{"name": "Alice"}
["apple", "banana"]
"Hello World"
42
true
Lines must be separated by the newline character \n (LF, U+000A). Carriage return \r is optional before \n (CRLF).
{"id": 1}\n
{"id": 2}\n
{"id": 3}Files must use UTF-8 encoding. This ensures international character support and compatibility across platforms.
{"name": "Müller"}
{"city": "北京"}
{"emoji": "🔥"}Unlike JSON arrays, JSONL does not use commas between lines. Each line is independent.
{"user": "alice"}
{"user": "bob"}
// No commas between lines!Each JSON value must be contained on a single line. Multi-line formatting is not allowed.
// ❌ Wrong (multi-line)
{
"name": "Alice"
}
// ✅ Correct (single line)
{"name": "Alice"}Empty lines are discouraged but may be tolerated by parsers. Best practice is to avoid them.
{"id": 1}
{"id": 2}
// Empty line above should be avoided
Recommended: application/jsonl
Alternative: application/x-ndjson
Legacy: text/plain
Common: .jsonl
Alternative: .ndjson
Alternative: .jsonlines
Required: UTF-8 (without BOM recommended)
// UTF-8 encoded characters
{"name": "José"}
{"location": "東京"}
{"symbol": "€"}
Standard: LF (\n, U+000A) - Unix/Linux/Mac
Accepted: CRLF (\r\n, U+000D U+000A) - Windows
Note: Parsers should handle both, but LF is preferred for cross-platform compatibility.
Now that you understand the specification, explore advantages, compare with other formats, and see real-world examples.