NDJSON: A Simple Guide to Streaming JSON Data

Introduction

Applications today often need to deliver information as soon as it becomes available. Waiting for an entire response before showing anything can make an application feel slow, especially when dealing with large datasets, real-time information, or AI-generated content. This is where NDJSON (Newline Delimited JSON) becomes useful.

NDJSON is a simple data format that allows applications to send multiple JSON objects independently, making it particularly suitable for streaming data over HTTP.

What Is NDJSON?

NDJSON is a format in which every line contains one complete JSON object. Instead of placing multiple objects inside a single JSON array, each object is separated by a newline.

For example, a normal JSON response could look like:

With NDJSON, the same information can be represented as:

The important difference is that each NDJSON line is an independent JSON object. A client can therefore process the first object without waiting for the second or third one.

Why Is NDJSON Useful?

The biggest advantage of NDJSON is its natural compatibility with streaming.

Consider an API that has to process thousands of records. With a conventional JSON response, the server may construct the complete response before sending it to the client. The user consequently has to wait until the operation is finished.

With NDJSON, the server can send records as they become available:

The client can immediately consume the first record while the server continues producing the others.

This provides several practical advantages:

• Faster perceived response time: Users can see information earlier.
• Incremental processing: Applications can process records individually.
• Lower memory requirements: There is no need to construct or hold one huge JSON document.
• Better support for large responses: Data can be consumed progressively.
• Simple structure: Developers only need to parse individual JSON objects.

This makes NDJSON particularly useful for applications where data is produced continuously rather than all at once.

How Does NDJSON Work?

NDJSON is commonly transmitted over HTTP with the following content type:

Content-Type: application/x-ndjson

The server writes JSON objects to the response stream, placing a newline after each object.

For example:

The client reads the HTTP response as a stream and identifies complete lines. Once a complete line has been received, parse it as JSON and use the resulting object immediately.

A simplified JavaScript implementation looks like this:

One important detail is that HTTP chunks and NDJSON lines are not necessarily the same thing. A network chunk can contain half of a JSON object, several objects, or part of multiple lines. Therefore, clients should maintain a buffer until a complete newline-delimited record is available.

NDJSON vs Traditional JSON

The main difference is how the response is treated.

Traditional JSON usually represents the response as one complete document:

The client generally treats the entire structure as one JSON value.

NDJSON instead represents the response as a sequence of independent JSON values:

This distinction makes NDJSON much more convenient when records need to be processed individually as they arrive.

Traditional JSON is still preferable when the application expects a relatively small, complete response and needs the entire structure together. NDJSON becomes more attractive when the response is large or generated progressively.

NDJSON vs SSE and WebSockets

NDJSON is not the only technology that supports streaming.

Server-Sent Events (SSE) is designed specifically for continuously sending events from a server to a browser over HTTP. SSE provides additional event-related features, making it useful for notifications and server-driven updates.

WebSockets provide persistent, two-way communication. Both the client and server can continuously send messages, which makes WebSockets suitable for applications such as multiplayer systems and interactive real-time communication.

NDJSON is simpler when the requirement is primarily to stream structured JSON records from a server to a client.

A useful way to distinguish them is:

• JSON: A complete structured response.
• NDJSON: A sequence of JSON records delivered incrementally.
• SSE: A stream of server-to-client events.
• WebSockets: A persistent two-way communication channel.

Where Is NDJSON Commonly Used?

NDJSON works well whenever information is generated or received progressively.

Typical use cases include:

• AI and LLM response streaming
• Real-time application logs
• Large data exports
• Data processing pipelines
• Monitoring systems
• Incremental search results
• Batch-processing APIs
• Event-driven applications

For example, an AI application could send separate NDJSON records containing text fragments, metadata, tool results, or status updates. The frontend can process each record immediately rather than waiting for the full AI response.

However, NDJSON should not be used simply because it supports streaming. For a small API response generated instantly, standard JSON is usually simpler and more appropriate.

Conclusion

NDJSON provides a straightforward way to stream structured information. Its defining principle is simple: one JSON object per line.

This structure allows servers to send records progressively and enables clients to process them as they arrive. As a result, NDJSON can improve perceived responsiveness, simplify large-data processing, and work particularly well for streaming APIs.

The choice between JSON, NDJSON, SSE, and WebSockets ultimately depends on the communication pattern an application needs. For straightforward server-to-client streaming of independent JSON records, NDJSON is a lightweight and practical option.