NDJSON Complete Guide: Newline Delimited JSON Explained

The NDJSON Specification

The official NDJSON specification at github.com/ndjson/ndjson-spec is intentionally minimal. It defines a simple convention for serializing multiple JSON values in a single text stream. The core rules are straightforward:

The specification explicitly avoids adding headers, metadata, or schema information to the format. This keeps NDJSON as simple as possible and compatible with standard Unix text processing tools. Any valid JSON value is allowed on each line, though in practice most NDJSON files contain JSON objects with a consistent set of keys.

• Each line MUST contain exactly one valid JSON value (object, array, string, number, boolean, or null).
• Lines are separated by the newline character '\n' (U+000A). The carriage return '\r' (U+000D) may appear before '\n' but is not required.
• A trailing newline after the last JSON value is allowed but not required.
• Each JSON value must not contain unescaped newline characters within the value itself.

Because the rules are minimal, NDJSON is easy to generate from any programming language that has a JSON serializer. Simply serialize each record, append a newline, and write it to the output. No closing brackets, no trailing commas, no enclosing array structure to worry about.

NDJSON MIME Type: application/x-ndjson

The registered MIME type for NDJSON is application/x-ndjson. This content type is used in HTTP headers to indicate that the response body contains newline-delimited JSON data. Many streaming APIs, including the GitHub API, Docker Registry API, and Elasticsearch bulk API, use this MIME type to deliver NDJSON responses.

Content-Type: application/x-ndjson

# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream

# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');

Some APIs also accept application/json-seq (RFC 7464) or text/plain as alternatives. However, application/x-ndjson is the most widely adopted MIME type for newline-delimited JSON streams. When building a new API that streams JSON records, use application/x-ndjson for maximum compatibility.

NDJSON in HTTP Streaming APIs

NDJSON is the de facto standard for HTTP streaming APIs that deliver real-time data. When a server sends an NDJSON response, the client can begin processing the first record as soon as it arrives, without waiting for the entire response to complete. This is faster and more memory-efficient than returning a large JSON array.

Popular services that use NDJSON streaming include Docker Registry (image layer events), Elasticsearch (bulk operations), Apache CouchDB (changes feed), and many modern event-driven APIs. The pattern works well with Server-Sent Events alternatives, real-time log tailing, and progressive data loading in web applications.

import express from 'express';

const app = express();

app.get('/api/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');

  // Simulate streaming events
  let id = 0;
  const interval = setInterval(() => {
    id++;
    const event = {
      id,
      type: 'heartbeat',
      timestamp: new Date().toISOString(),
    };
    res.write(JSON.stringify(event) + '\n');

    if (id >= 100) {
      clearInterval(interval);
      res.end();
    }
  }, 100);

  req.on('close', () => clearInterval(interval));
});

app.listen(3000);

async function* readNdjsonStream(url) {
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-ndjson' },
  });

  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (line.trim()) yield JSON.parse(line);
    }
  }
  if (buffer.trim()) yield JSON.parse(buffer);
}

// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
  console.log('Received:', event);
}

NDJSON and JSONL: Interoperability

NDJSON and JSONL (JSON Lines) are functionally identical formats. Both store one JSON value per line, separated by newline characters. A file that is valid NDJSON is also valid JSONL, and vice versa. You can rename a .ndjson file to .jsonl (or the other way around) without changing a single byte of content, and every tool that reads one format will read the other.

The only differences are cosmetic: NDJSON comes from github.com/ndjson/ndjson-spec and uses the .ndjson extension with the application/x-ndjson MIME type, while JSONL comes from jsonlines.org and uses the .jsonl extension. In practice, most developers treat the two names as synonyms. If your project already uses JSONL, there is no need to migrate to NDJSON, and if a library says it supports NDJSON, it will work with your .jsonl files without any changes.