JSON Lines and NDJSON Format Reference

JSON Lines stores one complete JSON value on each physical line. It supports streaming and large datasets without wrapping every record in one in-memory array.

Basic structure

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

Each non-empty line is independently valid JSON. There is no opening bracket, closing bracket, or comma between records. A newline terminator after the last record is strongly useful because files can be concatenated safely. Lines commonly end with LF; parsers can accept CRLF by removing the line terminator before JSON parsing.

Text encoding and line breaks

Use UTF-8 and avoid a byte-order mark. JSON strings cannot contain an unescaped control-character line break, so embedded newlines appear as \n within the one physical record line. Pretty-printing a record across several lines breaks the format. Producers should serialize one compact JSON value, append a newline, then flush according to throughput needs.

Streaming behavior

A consumer can read one bounded line, parse it, process or enqueue the record, and release memory before reading the next. This is useful for logs, exports, machine-learning datasets, and bulk API operations. Apply maximum line length and total-size limits; one attacker-controlled line can still exhaust memory if the reader waits indefinitely for a newline.

Value shape and schemas

Each line can technically be any JSON value, but interoperable datasets usually define one object schema. Document required fields, types, nullability, and versioning. Validate records independently and include a safe line number in errors. Do not assume that a valid first record proves the entire stream is valid.

Error strategies

A strict import can stop at the first invalid line and leave the operation uncommitted. A tolerant pipeline can route rejected records to a separate error stream while continuing. Choose explicitly and report counts for accepted, rejected, and retried records. Avoid silently skipping blank or malformed lines unless the contract permits it, and never log sensitive record contents by default.

Media type and file extensions

The extensions .jsonl and .ndjson are both common. Media-type conventions vary across implementations, including NDJSON-specific and JSON Lines-specific names. Document and validate the exact type your endpoint accepts instead of relying on a universal assumption. For downloads, a clear filename and content disposition improve tooling behavior.

Compression and concatenation

Large JSON Lines files compress well with gzip because field names repeat. Describe compression through the transport or filename convention and decompress with size limits. Newline-terminated files can be concatenated byte-for-byte, provided encoding and record schema are compatible. Merging does not sort, deduplicate, or reconcile versions automatically.

Frequently Asked Questions

Related Tools and Guides