newline-delimited JSON (NDJSON)

NDJSON, short for newline-delimited JSON, is a plain-text format that stores a sequence of JSON values with exactly one value per line. Each line is a complete JSON document, most often an object, and a newline character separates the records.

Each record is serialized without internal line breaks, so a newline can only mean the end of a record. JSON makes this safe because raw line breaks aren’t allowed inside strings, where any newline must be escaped as \n. A whole NDJSON file isn’t valid JSON, but each line is, so a parser reads it one line at a time. Three records take three lines:

{"id": 1, "name": "Ada Lovelace", "active": true}
{"id": 2, "name": "Grace Hopper", "active": false}
{"id": 3, "name": "Alan Turing", "active": true}

Because every line stands alone, programs can stream records over a socket or pipe, append new ones without rewriting the file, and skip a malformed line without losing the rest:

That makes the format a common choice for log files, bulk-import APIs, and machine learning training datasets, and it pairs naturally with line-oriented Unix tools.

The same convention also circulates as JSON Lines (JSONL), which uses the .jsonl file extension, while NDJSON files use .ndjson and the application/x-ndjson media type. Both require UTF-8 as the text encoding. In Python, decoding each line of such a file with json.loads() recovers the records one by one.

Related Resources

Tutorial

Working With JSON Data in Python

Use the Python json module to convert, read, write, and validate JSON data for APIs, config files, and on-disk storage.

intermediate python stdlib

For additional information on related topics, take a look at the following resources:

• Working With JSON in Python (Course)
• TinyDB: A Lightweight JSON Database for Small Projects (Tutorial)
• Reading and Writing Files in Python (Course)
• Reading and Writing Files With pandas (Course)
• Reading and Writing CSV Files (Course)
• Serialize Your Data With Python (Tutorial)
• Logging Inside Python (Course)
• Working With JSON Data in Python (Quiz)
• TinyDB: A Lightweight JSON Database for Small Projects (Quiz)
• Serialize Your Data With Python (Quiz)