NDJSON (Newline Delimited JSON)

NDJSON (Newline Delimited JSON) is a streaming serialization format specified by ndjson.org that structures structured datasets into individual JSON values separated by standard newline characters (\n or \r\n). Widely registered under the MIME media type application/x-ndjson, NDJSON is functionally identical to JSON Lines (JSONL) and provides an optimal foundation for HTTP chunked transfer streaming, distributed data lakes (Apache Spark, Presto, DuckDB), log collectors (Fluentd, Logstash), and search engine bulk indexing (Elasticsearch, OpenSearch).

Convert between NDJSON files and formatted JSON arrays with our private, in-browser JSONL Converter or convert line-delimited records to columnar analytics formats using our JSON to Parquet Converter.

---

Technical Specifications at a Glance

Specification	Details
Official Standard	NDJSON Specification (ndjson.org) / JSON Lines
MIME Media Type	application/x-ndjson or application/jsonlines
File Extensions	.ndjson, .jsonl, .ldjson
Encoding	Strict UTF-8 without Byte Order Mark (BOM)
Line Delimiter	\n (Unix Line Feed) or \r\n (Windows CRLF)
Streaming Complexity	$O(1)$ memory consumption per stream chunk

---

Why Elasticsearch & Search Engines Use NDJSON

Search engines such as Elasticsearch and OpenSearch require NDJSON for their high-throughput _bulk API endpoints. Because each action metadata line is paired with a subsequent document source line, the ingestion engine can parse, route, and dispatch individual documents across cluster shards without buffering or deserializing large root documents in memory:

{"index":{"_index":"ecommerce_orders","_id":"ord_1001"}}
{"customer":"Alice","total":149.50,"currency":"USD","status":"completed"}
{"index":{"_index":"ecommerce_orders","_id":"ord_1002"}}
{"customer":"Bob","total":49.00,"currency":"USD","status":"pending"}

---

NDJSON in Cloud Data Warehouses & Analytics

Modern analytical query engines ingest NDJSON natively due to its split-friendly architecture:

1. Google BigQuery: Loads newline-delimited JSON directly using bq load --source_format=NEWLINE_DELIMITED_JSON my_dataset.orders gs://my_bucket/orders.ndjson.
2. DuckDB: Queries local or remote NDJSON files with automatic schema detection: SELECT * FROM read_ndjson_auto('orders.ndjson') WHERE total > 100.
3. Snowflake: Stages and copies newline-delimited records into analytical tables via COPY INTO orders FROM @my_stage FILE_FORMAT = (TYPE = 'JSON').

---

Processing NDJSON in Modern TypeScript / Node.js

import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';

async function streamNdjson(filePath: string) {
  const fileStream = createReadStream(filePath, { encoding: 'utf8' });
  const rl = createInterface({ input: fileStream, crlfDelay: Infinity });

  let processedRecords = 0;

  for await (const line of rl) {
    const trimmed = line.trim();
    if (!trimmed) continue;

    try {
      const record = JSON.parse(trimmed);
      processedRecords++;
      // Handle individual record in constant O(1) memory
    } catch (err) {
      console.error(`Malformed NDJSON row encountered:`, err);
    }
  }

  console.log(`Streamed ${processedRecords} records successfully.`);
}

---

Frequently Asked Questions

What is the difference between NDJSON and JSONL?

There is no functional difference. "NDJSON" stands for Newline Delimited JSON (standardized at ndjson.org), while "JSONL" stands for JSON Lines (standardized at jsonlines.org). Both specifications dictate that every line is an independent, valid JSON document separated by a newline (\n).

Can NDJSON files contain nested arrays and objects?

Yes. Each line in an NDJSON document can contain arbitrarily deep nested objects and arrays, provided that any literal newlines inside string values are properly escaped as \n.

How do I convert NDJSON to a standard JSON array online?

Paste your NDJSON content into our JSONL Converter tool, which automatically detects line-delimited records and converts them into a formatted, syntactically valid JSON array.