The Complete Guide to Json To Ndjson: Everything You Need to Know

NDJSON — Newline Delimited JSON, also called JSON Lines or JSONL — is a streaming-friendly format in which each line of a plain text file is a self-contained, valid JSON value. Unlike a standard JSON array that must be read entirely into memory before any record can be accessed, an NDJSON file can be processed line by line. This makes it ideal for log pipelines, data imports, machine learning datasets, Elasticsearch bulk indexing, and any workflow where records need to be consumed incrementally or in parallel.

The challenge is that most application exports and API responses produce standard JSON arrays. Converting that JSON array into NDJSON — one object per line — is a straightforward transformation, but doing it correctly with large files, Unicode content, and nested objects requires careful handling. The JSON to NDJSON Converter on this site performs the transformation entirely in your browser: no file is uploaded to a server, and no data leaves your device.

This guide explains what NDJSON is, why the format exists, how the conversion works under the hood, and the best practices developers should follow when producing and consuming NDJSON files.

Connect on LinkedIn →

What Is NDJSON?

NDJSON stands for Newline Delimited JSON. The format is defined by a simple rule: each line of the file must be a complete, valid JSON value, and lines are separated by a single newline character (\n). There is no outer container — no surrounding array brackets, no commas between records, no shared structure that links one line to the next.

The format is also known as JSON Lines (JSONL). The two names refer to the same convention and are used interchangeably in the developer community. File extensions vary: .ndjson and .jsonl are both common; some systems use plain .json for NDJSON files, which can cause confusion.

A minimal NDJSON file containing three records looks like this:

{"id":1,"name":"Alice","role":"admin"}
{"id":2,"name":"Bob","role":"editor"}
{"id":3,"name":"Carol","role":"viewer"}

Each line is independently parseable. A program reading this file can process the first line, discard it from memory, then process the second line, and so on. This property — streaming parseability — is what distinguishes NDJSON from a standard JSON array.

JSON Array vs. NDJSON: Key Differences

A standard JSON array containing the same three records looks like this:

[
  {"id":1,"name":"Alice","role":"admin"},
  {"id":2,"name":"Bob","role":"editor"},
  {"id":3,"name":"Carol","role":"viewer"}
]

The structural differences have practical consequences for how each format can be used:

• Memory footprint. To parse a JSON array, the entire file must be read into memory and parsed as a single value before any record can be accessed. For a 500 MB JSON export, this means holding 500 MB of raw text plus the parsed object graph in memory simultaneously. An NDJSON file of the same size can be processed with a fixed memory footprint regardless of the file's total size — each line is read, parsed, used, and discarded independently.
• Streaming. NDJSON can be streamed: a producer can write records to a file or network socket one at a time, and a consumer can begin reading before the producer has finished writing. A JSON array cannot be streamed in the same way because its validity depends on the closing ] that only appears after all records have been written.
• Concatenation. Two NDJSON files can be concatenated by appending one to the other — the result is a valid NDJSON file containing all records from both. Two JSON array files cannot be concatenated to produce a valid JSON array without parsing and re-serializing both.
• Append-only writes. Adding a new record to an NDJSON file is an append operation: write a newline and the new JSON object. Adding a record to a JSON array requires modifying the closing ] and the preceding comma, which is a rewrite operation on the existing file content.
• Toolability. Line-oriented Unix tools — grep, awk, sed, wc — work naturally on NDJSON files because each record is a line. A wc -l on an NDJSON file gives the record count. grep "error" on an NDJSON log file returns all error records. These operations are not possible on a JSON array without a JSON-aware parser.

How the Conversion Works

The JSON to NDJSON conversion is a two-step process: parse the input as JSON, then serialize each element of the top-level array back to a compact single-line string.

Step 1 — Parse. The converter calls JSON.parse() on the full input text. This validates that the input is syntactically correct JSON before any conversion is attempted. If the input contains a syntax error — a missing comma, an unescaped character, a JavaScript-style comment — JSON.parse() throws an exception with a description of the problem, and the converter reports the error without producing any output.

Step 2 — Serialize. If the parsed value is an array, the converter iterates over each element and calls JSON.stringify(element) to produce a compact, single-line JSON representation. The elements are joined with newline characters (\n). The result is a valid NDJSON document where each line is one element of the original array.

JSON.stringify() with no formatting arguments produces the most compact valid representation of a value: all whitespace is removed, including indentation and line breaks that may have been present in the input. This is exactly what NDJSON requires — each line must be a complete JSON value with no embedded newlines.

Unicode characters are preserved: the converter reads the file using TextDecoder with UTF-8 encoding, and writes the output as a UTF-8 Blob. Multi-byte characters — emoji, CJK ideographs, accented Latin characters — pass through the conversion without modification.

The output file is named by replacing the .json extension of the input file with .ndjson. For pasted input, the output is named pasted-input.ndjson.

File Upload vs. Paste Mode

The converter supports two input modes, switchable via the tabs at the top of the tool box.

File upload mode accepts a .json file dropped onto the drop zone or selected via the file browser. The file is read using the FileReader API, which reads the file contents entirely into an ArrayBuffer in the browser's memory. No network request is made. The converter handles files up to 200 MB — appropriate for large API exports, database dumps, and ML dataset files. File reading happens asynchronously; the interface remains responsive while the file is being read.

Paste mode accepts raw JSON pasted directly into a textarea. This is useful for quick conversions of small JSON snippets copied from an API response, a developer console, or documentation. The textarea accepts any valid JSON — a compact single-line string, a pretty-printed multi-line document, or anything in between. The conversion logic is identical in both modes; only the input source differs.

If a file is dropped on the tool while paste mode is active, the converter automatically switches to file mode and loads the dropped file. This makes it easy to switch between modes without explicitly clicking the tab.

Handling Single Objects and Primitives

The NDJSON format is defined for arrays of values — each element becomes one line. When the input JSON is not an array, the converter handles two cases:

Single object. If the input parses to a JSON object (rather than an array), the converter writes a single-line NDJSON file containing that one object and displays a warning: "Input is a single JSON object, not an array. The output contains 1 record." This is the correct behavior — a single object is a valid NDJSON file with one record — but the warning signals that the input may not be what was intended. The most common cause is an API response that wraps the data array in an outer object (e.g., {"data": [...], "meta": {...}}); in that case, the user should extract the inner array before converting.

Primitive value. If the input parses to a string, number, boolean, or null, the converter writes a single-line NDJSON file containing that value and displays a warning describing the type. Primitive values are valid JSON but unusual as NDJSON records; the warning helps the user identify a likely input error.

Empty array. If the input is an empty array ([]), the converter produces an empty NDJSON file with zero lines and displays a warning: "Input array is empty — the output file will contain no lines." An empty NDJSON file is valid, but is usually not the intended result.

Common Use Cases

Elasticsearch and OpenSearch bulk indexing. The Elasticsearch Bulk API requires a specific NDJSON format: alternating action lines and data lines. The JSON to NDJSON Converter produces the data portion — one JSON object per line — which can then be combined with action lines for bulk indexing. Converting a JSON export from a database or another system into NDJSON is the first step in preparing data for Elasticsearch ingestion.

Kafka and streaming pipelines. Message brokers like Apache Kafka, AWS Kinesis, and Google Pub/Sub consume records individually. When a JSON array export needs to be fed into a streaming pipeline, the records must first be split into individual messages. Converting to NDJSON produces a line-oriented file that can be read line by line and published as individual messages using a shell script, Python script, or pipeline tool.

Machine learning datasets. The OpenAI fine-tuning API, Hugging Face datasets, and many other ML frameworks accept JSONL (JSON Lines) as a dataset format. A training dataset prepared as a JSON array must be converted to JSONL before upload. The converter handles this transformation for datasets of any size, with the privacy guarantee that the training data — which may include proprietary text, code, or personally identifiable content — never leaves the browser.

BigQuery and data warehouses. Google BigQuery's streaming insert API and load job API accept NDJSON as an input format. Converting a JSON export from an OLTP database into NDJSON is a common step in loading data into BigQuery for analytical queries. The converter produces a file that can be uploaded directly to a BigQuery load job without intermediate transformation.

Command-line processing with jq. The jq command-line JSON processor operates on JSON input from stdin or a file. When processing large datasets, it is more efficient to pipe NDJSON line by line than to load an entire JSON array. Converting a JSON file to NDJSON before processing with jq enables streaming transformations, filtering, and aggregation on files that would be too large to process as a single JSON value.

Log file analysis. Applications that log structured JSON events typically write one JSON object per line — an NDJSON file. When a tool produces logs as a JSON array instead of NDJSON, converting the array to NDJSON makes the log file compatible with log analysis tools, grep-based filtering, and line-count-based metrics.

Private data conversion. JSON files containing API credentials, PII, financial records, or proprietary business data cannot be safely uploaded to a third-party conversion service. The JSON to NDJSON Converter processes the file entirely in the browser — no data is transmitted to any server. This makes it safe to convert sensitive files that could not otherwise be converted using an online tool.

Best Practices

Validate the input before converting. If the input JSON comes from an untrusted source or was produced by an export script, validate it before converting. The converter reports JSON syntax errors, but a valid JSON array may still have data quality issues — inconsistent key sets, null values in unexpected places, values with the wrong type. Use the JSON Validator to inspect the input before conversion.

Check the record count. After conversion, compare the reported record count against the expected number of records from the source system. A mismatch indicates that some records were dropped during export, that the input array was nested inside an outer object, or that the file was truncated. The converter displays the record count in the stats panel immediately after conversion.

Use LF line endings. The NDJSON specification uses the Unix LF character (\n) as the record delimiter. The converter always produces LF line endings. If the resulting file will be processed by a tool that is sensitive to line endings, confirm that the tool accepts LF-terminated files (most do).

Do not embed unescaped newlines in string values. JSON.stringify() escapes any literal newlines in string values as \n, so this is handled automatically by the converter. However, if you manually edit an NDJSON file or construct records programmatically, be aware that an unescaped newline inside a string value will split the record across two lines, corrupting both the record and all subsequent records.

Flatten before converting for tabular consumers. Tools like BigQuery and most SQL databases expect NDJSON records to have a flat or mildly nested structure. Deeply nested JSON objects — objects containing arrays of objects containing further nested objects — may not map cleanly to a tabular schema. Consider flattening the records before conversion if the target system has schema constraints.

Prefer paste mode for small snippets. For JSON snippets under a few kilobytes — API response examples, test fixtures, documentation samples — paste mode is faster than saving to a file and uploading. The conversion is instantaneous for small inputs and the result can be copied from the preview panel without downloading a file.

Use the preview panel to verify output. The converter shows the first five lines of the NDJSON output in a preview panel before downloading. Verify that the first few records look correct — the right fields, the right values, no unexpected characters — before downloading the full file. For large files, a visual check of the first few records catches most conversion errors without requiring a full file inspection.

Tools That Consume NDJSON

NDJSON is a widely supported format. The following tools and services accept it natively:

• Elasticsearch / OpenSearch — Bulk API ingestion (_bulk endpoint)
• Google BigQuery — Load jobs and streaming inserts
• Apache Spark — spark.read.json() reads NDJSON by default
• Hugging Face Datasets — JSONL dataset format
• OpenAI Fine-tuning API — JSONL training files
• MongoDB mongoimport — --type json with one document per line
• ClickHouse — JSONEachRow input format
• DuckDB — read_json_auto() handles NDJSON files
• jq — Streams NDJSON with -c flag for compact output
• Vector, Logstash, Fluentd — Log pipeline ingestion
• AWS Kinesis Data Firehose — Record-per-line delivery format
• Azure Event Hubs — NDJSON event streams

If a tool requires a specific NDJSON variant — for example, Elasticsearch's Bulk API requires alternating action and data lines rather than data lines alone — the output of this converter provides the data portion that can be combined with the appropriate action lines using a script or pipeline tool.