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

Learn how to work with JSON data in Python using the json module. Convert, read, write, and validate JSON files and handle JSON data for APIs and storage.

intermediate python stdlib

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

• Serialize Your Data With Python (Tutorial)
• Working With JSON in Python (Course)
• Reading and Writing Files in Python (Course)
• Logging Inside Python (Course)
• Reading and Writing Files With pandas (Course)
• Reading and Writing CSV Files (Course)
• Working With JSON Data in Python (Quiz)
• Serialize Your Data With Python (Quiz)