Understanding NDJSON Format

NDJSON, also known as Newline Delimited JSON or JSON Lines, is a text format that stores one complete JSON value per line, most commonly an object for record-oriented data. This format is particularly useful for:

• Streaming large datasets
• Processing records incrementally
• Log file formats
• Data exchange between systems
• Machine learning data preparation

NDJSON vs JSON vs JSONL

NDJSON Example

Here's a simple NDJSON example with user data:

{"name": "John Doe", "age": 30, "email": "john@example.com"}
{"name": "Jane Smith", "age": 25, "email": "jane@example.com"}
{"name": "Bob Johnson", "age": 35, "email": "bob@example.com"}

NDJSON Format Specification

The NDJSON format follows these rules:

1. Each line must contain exactly one complete JSON value
2. Each value must be valid JSON (properly formatted)
3. Values are separated by newline characters (\n)
4. No trailing commas or array wrapping
5. Empty lines should be ignored

Working with NDJSON in Different Languages

Python

import json

# Reading NDJSON
with open('data.ndjson', 'r') as f:
    for line in f:
        if line.strip():
            data = json.loads(line)
            print(data)

# Writing NDJSON
data = [{"name": "John", "age": 30}, {"name": "Jane", "age": 25}]
with open('output.ndjson', 'w') as f:
    for item in data:
        f.write(json.dumps(item) + '\n')

JavaScript

// Reading NDJSON
const fs = require('fs');
const readline = require('readline');

const fileStream = fs.createReadStream('data.ndjson');
const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity
});

rl.on('line', (line) => {
    if (line.trim()) {
        const data = JSON.parse(line);
        console.log(data);
    }
});

// Writing NDJSON
const data = [{"name": "John", "age": 30}, {"name": "Jane", "age": 25}];
const ndjson = data.map(item => JSON.stringify(item)).join('\n');
fs.writeFileSync('output.ndjson', ndjson);

NDJSON vs JSONL: Are They the Same?

Yes, NDJSON and JSONL are essentially the same format. Both terms refer to newline-delimited JSON files. The difference is mainly in naming:

• NDJSON - "Newline Delimited JSON" (more descriptive)
• JSONL - "JSON Lines" (shorter, more common)

Common NDJSON Use Cases

NDJSON Tools and Converters

Need to work with NDJSON files? Check out these helpful tools:

NDJSON Best Practices

1. Validate each line - Ensure every line contains valid JSON
2. Handle empty lines - Skip or ignore empty lines when processing
3. Use streaming - Process large files line by line to avoid memory issues
4. Consistent encoding - Use UTF-8 encoding for international characters
5. Error handling - Implement proper error handling for malformed lines

How NDJSON Works

NDJSON has no enclosing structure. Each line stands alone, so a parser can read one record, process it, and discard it before touching the next line. That is what makes NDJSON ideal for streaming:

• Stream as it grows — tail an NDJSON file (e.g. tail -f app.ndjson) and process new records the moment they are appended.
• Split on line boundaries — divide huge files across machines or workers without parsing anything first.
• Append without rewriting — add a record by writing one more line to the end of the file.
• Survive bad lines — skip a malformed line and keep processing the rest, unlike a single JSON document where one error breaks everything.

For the mechanics in another syntax, see the JSONL parser guide. To compare the trade-offs directly, read our JSONL vs JSON comparison.

How to Open an NDJSON File

Any text editor opens NDJSON, but record-by-record browsing needs a dedicated tool:

1. Online viewer — drop the file into our NDJSON Viewer to inspect records by line and find malformed JSON.
2. Text editor — VS Code, Sublime Text, or even Notepad work for small files; each line is human-readable JSON.
3. Command line — preview with head -5 data.ndjson or validate every line with python -c "import json,sys; [json.loads(l) for l in sys.stdin]" < data.ndjson.
4. As a spreadsheet — convert first with our JSONL to CSV converter and open the result in Excel or Google Sheets.

Frequently Asked Questions

Get Started with NDJSON