NDJSON vs JSON: structure, streaming, and safe conversion

JSON is one value; NDJSON is a sequence of values

An ordinary JSON document contains one JSON text. That value can be an object, array, string, number, true, false, or null. A file containing many records therefore often uses one top-level array. The parser normally needs enough input to understand that complete enclosing value.

Newline Delimited JSON, or NDJSON, writes each independent JSON text on its own physical line. The NDJSON specification requires UTF-8, accepts LF or CRLF delimiters, and says serialized JSON texts must not contain literal newline or carriage-return characters. A newline that belongs inside a string is encoded as backslash-n, so it does not split the record.

[
  { "id": 1, "status": "queued" },
  { "id": 2, "status": "done" },
  ["heartbeat", 1712345678]
]

{"id":1,"status":"queued"}
{"id":2,"status":"done"}
["heartbeat",1712345678]

Choose NDJSON for record-oriented processing

NDJSON works well for append-oriented logs, command-line pipelines, event exports, and bounded streams because a consumer can process one complete line at a time. A bad record can be reported with its physical line number, and producers can emit the next value without rewriting a top-level array or waiting for the whole data set.

That convenience does not make NDJSON a universal replacement for JSON. It has no single outer object for document-level metadata, relationships between records are an application concern, and pretty-printing one record across several lines breaks the framing rule. Choose ordinary JSON for configuration files, API documents, nested values reviewed as a whole, and formats whose contract requires application/json.

• Use NDJSON when each line is independently meaningful and incremental processing matters.
• Use a JSON array when order, completeness, and one atomic document are part of the contract.
• Confirm the receiver's media type and framing rules instead of relying only on a .json or .ndjson filename.

Validate every nonblank line as strict JSON

Each NDJSON record still follows RFC 8259. Comments, trailing commas, single-quoted strings, NaN, and Infinity remain invalid. A line can be any JSON value, not only an object; arrays and primitives are allowed unless an application adds a narrower schema. The core NDJSON specification allows a parser to ignore empty lines only when that behavior is documented and preferably configurable.

This site's NDJSON tools ignore blank lines and validate every nonblank line independently. They report a line-specific problem rather than interpreting several lines as one JSON document. After syntax validation, apply a record schema or application checks if every line must have fields such as id, timestamp, or event type.

Convert by preserving one value per record

Converting NDJSON to ordinary JSON usually means parsing each nonblank line and collecting the values into one array. The three-line example becomes the three-item array shown above. This changes the container and requires enough memory for the complete result, but it should not invent fields or coerce primitive values.

The reverse operation should begin with a top-level JSON array and serialize each item as one compact JSON text followed by a line delimiter. Converting an arbitrary object by emitting each property would create an undocumented mapping, so a predictable converter should reject that input or require an explicit policy.

Keep record boundaries explicit in production

• Use UTF-8 and a documented LF or CRLF delimiter policy.
• Bound maximum line size, total bytes, nesting depth, and record count before parsing untrusted data.
• Record the failing line number without logging sensitive record contents.
• Decide whether empty lines are rejected or ignored and keep that behavior consistent across producers and consumers.
• Use application/x-ndjson only when the receiver supports it; ordinary JSON uses application/json.

NDJSON improves framing, not trust. Every record can still contain untrusted values, oversized structures, or fields that violate an application contract. Treat line-by-line parsing as the first boundary, then apply the same schema, authorization, retention, and privacy controls that the equivalent JSON records require.