Skip to main content

JSONL Definition

Official specification and technical standards for JSON Lines format

Formal Definition

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.

JSONL vs Standard JSON

NOT a Single Valid JSON Document

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}

No Commas Between Lines

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"}
]

No Outer Array

The entire collection of objects is not wrapped in an outer array ([ and ]). Each line stands alone.

Preserves JSON Structure

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"}}

Format Rules

Rule 1: JSON Values

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

Rule 2: Line Separator

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}

Rule 3: UTF-8 Encoding

Files must use UTF-8 encoding. This ensures international character support and compatibility across platforms. 

{"name": "Müller"}
{"city": "北京"}
{"emoji": "🔥"}

Rule 4: No Trailing Commas

Unlike JSON arrays, JSONL does not use commas between lines. Each line is independent. 

{"user": "alice"}
{"user": "bob"}
// No commas between lines!

Rule 5: Single Line

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"}

Rule 6: Empty Lines

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

Technical Specifications

MIME Type

Recommended: application/jsonl

Alternative: application/x-ndjson

Legacy: text/plain

File Extensions

Common: .jsonl

Alternative: .ndjson

Alternative: .jsonlines

Character Encoding

Required: UTF-8 (without BOM recommended) 

// UTF-8 encoded characters
{"name": "José"}
{"location": "東京"}
{"symbol": "€"}

Line Endings

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.

Standards & References

  • JSON Specification: RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format
  • UTF-8 Encoding: RFC 3629 - UTF-8, a transformation format of ISO 10646
  • Newline Character: Unicode U+000A (Line Feed) as defined in Unicode Standard
  • Alternative Names: NDJSON (Newline Delimited JSON), JSON Lines, Line-delimited JSON

Learn More About JSONL

Now that you understand the specification, explore advantages, compare with other formats, and see real-world examples.

See Advantages View Comparisons Browse Examples