Developer guide
JSON Lines (NDJSON) vs JSON vs CSV: A Practical Guide
Half the time a “big JSON file” is actually a collection of records that would be far easier to stream, append and debug as individual lines. JSON Lines — also called NDJSON — is that format. This guide explains what it is, when it beats plain JSON and CSV, and how the trade-offs shake out in the real world.
Written by Benjamin Rotshtein
Updated
- When is JSON Lines the right choice?
- When records keep getting appended over time, need streaming, or must be processed one at a time — logs, events, training sets and incremental exports.
- JSON Lines or CSV?
- CSV if your data is flat, homogeneous and you want maximum size savings; JSON Lines when records have types, nesting, or can change shape over time.
- Is JSON Lines a single JSON or many JSON?
- It is many small JSON objects — one per line — designed to be streamed. Forever instead of one big array that must parse in one call.
What is JSON Lines?
JSON Lines — also styled and — parsable as NDJSON — is a text format where each line is a single, self-contained JSON object. There is no enclosing array; the file is just line after line of JSON, each ending in a newline.
{"ts":1752900000,"user":42,"event":"login","ok":true}
{"ts":1752900001,"user":43,"event":"page_view","ok":true}
{"ts":1752900002,"user":44,"event":"buy","ok":true}Because each line is complete and independent, you can read the first line before generating the millionth, append lines without rewriting the file, and skip a malformed line without losing the rest of the file.
How it differs from plain JSON and CSV
| Criterion | CSV | JSON | JSON Lines |
|---|---|---|---|
| Structure | Flat table | One nested document | Many JSON objects, one per line |
| Types | All text | Explicit | Explicit per object |
| Streaming | Line by line, flat | Whole file must buffer | Line by line, ✓ nesting |
| Append / reuse | Append a row | Rewrite entire file | Append a line |
| Size | Smallest | Largest (one file) | Larger than CSV, per line |
| Main use | Spreadsheets, DB imports | APIs, config | Logs, streams, ML datasets |
When JSON Lines wins
Pick JSON Lines when your data looks like a stream of records:
- Logs and events: each event is a record you batch-append without rewriting.
- Large batches: read/process one line at a time, keeping memory flat.
- Training data: many frameworks (Datasets, Spark) load NDJSON directly.
- Resilience: one corrupt line won't invalidate the rest of the file — unlike a single JSON doc.
- Fit parser per tool: Combine into arrays per small batch rather than one giant array.
The practical cost: keys repeat per line
The trade-off against JSON is that it repeats each object's keys. For flat tables, CSV offsets this by writing keys once in the header. JSON Lines sits in between: it keeps types and nesting, but a 100-column record repeats all 100 keys on every single line. For very wide, flat, identical rows, a header row CSV or JSON array will be more compact.
How to convert these formats safely
Converting between JSON Lines, a JSON array and CSV comes down to flattening and keeping know-when-a-record-ends. With our converters, data stays in your browser and never hits a server.
// JSON array -> JSON Lines
[{"a":1},{"a":2}] => {"a":1}
{"a":2}
// JSON Lines -> JSON array
{"a":1}
{"a":2} => [{"a":1},{"a":2}]Use the JSON to CSV converter, CSV to JSON converter or a JSON formatter to produce clean, validated output that streams or flattens the way you need.
Frequently asked questions
What is the difference between NDJSON and JSON?
A JSON file is one single document — a single object or array. JSON Lines (NDJSON) is many JSON objects, one per line, separated by newlines. NDJSON can be parsed line by line and streamed, whereas a single JSON document must be read, buffered and parsed as one unit.
Which is smaller, JSON Lines or CSV?
For the same flat table, CSV is usually smaller because it writes column names once in a header and stores every value as raw text. JSON Lines repeats the keys on every line, so it is larger, but it preserves types and nesting that CSV cannot.
When should I use JSON Lines instead of JSON?
When you have many records you want to append to over time, stream, or process one at a time — for example log files, training datasets, event pipelines, or exports you rebuild incrementally. Each line is independently parseable.
How is JSON Lines different from regular CSV for logs?
CSV is fine for flat, homogeneous rows but loses types and cannot represent nested fields. JSON Lines keeps full JSON objects per line, so heterogeneous records and nested structures come through intact, at the cost of more bytes per line.
Is JSON Lines the same as NDJSON?
Yes. NDJSON (Newline-Delimited JSON) and JSON Lines are the same format — one JSON object per line, each object on its own line, with no surrounding array. The main difference is the specification documentation: jsonlines.org vs ndjson.org use slightly different blank-line rules.
Can I convert a regular JSON array to JSON Lines?
Yes. Split a JSON array of objects into lines by outputting each object on its own line (you must also split top-level arrays across lines first, since a single JSON array cannot be streamed). Our converter can help you flatten a JSON array into newline-delimited objects.