What is NDJSON? Complete Guide to Newline Delimited JSON

Understanding NDJSON Format

NDJSON, also known as Newline Delimited JSON or JSON Lines, is a text format that stores multiple JSON objects, with each object on its own line. 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

Format	Structure	Use Case
JSON	Single object in array	API responses, config files
NDJSON	Multiple objects, one per line	Streaming, large datasets
JSONL	Same as NDJSON	Same as NDJSON

NDJSON Example

Here's a simple NDJSON example with user data:

users.ndjson

{"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:

Each line must contain exactly one JSON object
Objects must be valid JSON (properly formatted)
Objects are separated by newline characters (\n)
No trailing commas or array wrapping
Empty lines should be ignored

Working with NDJSON in Different Languages

Python

ndjson_example.py

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

ndjson_example.js

// 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)

💡 Pro Tip

While NDJSON and JSONL are the same format, JSONL is more widely adopted in the developer community. If you're building tools or APIs, consider supporting both terms for better discoverability.

Common NDJSON Use Cases

Data Streaming

Perfect for streaming large datasets where you need to process records one at a time without loading everything into memory.

Log Files

Many logging systems use NDJSON format because it's easy to append new log entries and parse incrementally.

Machine Learning

ML frameworks often use NDJSON for training data because it allows for efficient batch processing and streaming.

API Responses

Some APIs return NDJSON for large result sets to enable streaming responses and reduce memory usage.

NDJSON Tools and Converters

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

Our JSONL Tools (Also Work with NDJSON)

JSON to JSONL Converter - Convert JSON arrays to NDJSON format
JSONL Validator - Validate your NDJSON files for errors
JSONL Viewer - View and explore NDJSON files online
JSONL Parser - Parse and analyze NDJSON data

NDJSON Best Practices

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

Frequently Asked Questions

Is NDJSON the same as JSONL?

Yes, NDJSON and JSONL are the same format. NDJSON stands for "Newline Delimited JSON" while JSONL stands for "JSON Lines." Both refer to the same text format where each line contains one JSON object.

When should I use NDJSON instead of regular JSON?

Use NDJSON when you need to stream large datasets, process records incrementally, or work with log files. Regular JSON is better for small, structured data that fits in memory.

Can I convert NDJSON to JSON?

Yes, you can convert NDJSON to JSON by wrapping all the objects in an array. Use our JSONL Converter to easily convert between formats.

What's the MIME type for NDJSON?

The standard MIME type for NDJSON is application/x-ndjson or application/jsonl.

[ JSONL::Tools ]