JSONL vs JSON vs NDJSON vs CSV vs Parquet

Format comparison guide · updated 21 May 2026 · overview · spec · examples · best practices

Five formats that look interchangeable but solve different problems. JSON is for documents. JSONL and NDJSON are streamable record sets. CSV is for spreadsheets. Parquet is for analytical warehouses. Picking right matters — converting later is cheap with tools like ours, but discovering you picked wrong after writing 50 GB is painful.

The 30-second version

• JSON — one document, often hierarchical. Configs, API responses, single-record exchanges.
• JSONL / NDJSON — many independent records, one per line. Logs, datasets, streams, ML training data.
• CSV — tabular rows, all the same flat shape. Spreadsheets, simple exchange, BI imports.
• Parquet — typed columnar storage with metadata. Analytical workloads at scale.

If your data has nested structure and you want to stream/append, JSONL wins. If it's a single rich document, regular JSON. If it's a flat table for non-developers, CSV. If it's millions of rows for analytics, Parquet.

JSONL vs JSON

Round-trip both ways with JSON → JSONL and JSONL → JSON.

When to pick JSON over JSONL

• You're sending a single response over HTTP that fits comfortably in memory.
• The data is a document, not a set — e.g. a configuration file, a search response with nested facets, an OpenAPI spec.
• You need to cross-reference between records inside the same payload (a JSON array makes this easy; a JSONL stream doesn't).
• The consumer is a browser or a tool that expects a single document (JSON.parse on the whole body).

When to pick JSONL over JSON

• The data is a stream or batch of records, all the same shape.
• The file may not fit in memory.
• You want to append records over time without rewriting the file.
• You want line-based Unix tooling (head, tail, grep, wc, jq) to work directly.
• You want partial failure tolerance: one bad record shouldn't poison the rest.
• You're feeding an ML training pipeline, log aggregator, or warehouse importer — these almost universally expect JSONL.

JSONL vs NDJSON

Same format, different names. NDJSON is the spelling used in JavaScript / Node circles and pushed by ndjson.org. JSONL is the spelling used in Python, ML, and data engineering, and standardised by jsonlines.org. There is no functional difference.

If you receive .ndjson and your tool expects .jsonl (or vice versa), just rename the file. Both refer to "one JSON value per line, separated by \n." See the overview's naming section for history.

JSONL vs CSV

Round-trip with CSV → JSONL and JSONL → CSV.

When to pick CSV

• Your audience is non-developers who'll open the file in Excel or Sheets.
• The data is genuinely flat (no nested objects, no arrays inside cells).
• The file is going into a BI tool that prefers CSV imports.
• File size matters more than self-description.

When to pick JSONL over CSV

• You have nested data and don't want to flatten lossily.
• You need type distinctions (a number that looks like a leading-zero string ID — CSV can't represent both safely).
• Your downstream is a programming language, not a spreadsheet.
• You want resilience to one row being malformed.

JSONL vs Parquet

Convert with JSONL ↔ Parquet (DuckDB-WASM in your browser).

The typical workflow

Many data pipelines use both: JSONL for the landing zone / staging area / streaming transport (append-friendly, debuggable in a text editor), then Parquet for the queryable storage after a daily or hourly compaction (columnar reads, dictionary compression). Tools like dbt, Airbyte, and Snowflake's external tables understand this pattern out of the box.

Decision flowchart

Is the data ONE document (config, single API response)?
  └── Yes → JSON
  └── No  → continue

Are records flat with no nesting?
  └── Yes → audience non-developers?
              └── Yes → CSV
              └── No  → continue

Is the data at-rest for analytical queries (warehouse, BI)?
  └── Yes → Parquet
  └── No  → JSONL

Side-by-side: the same data in each format

JSON

{
  "users": [
    {"id": 1, "name": "Ada",     "active": true,  "tags": ["math", "code"]},
    {"id": 2, "name": "Babbage", "active": false, "tags": ["engine"]}
  ]
}

JSONL

{"id":1,"name":"Ada","active":true,"tags":["math","code"]}
{"id":2,"name":"Babbage","active":false,"tags":["engine"]}

CSV (lossy — arrays flattened)

id,name,active,tags
1,Ada,true,"math|code"
2,Babbage,false,engine

Parquet (binary; logical schema shown)

id      : int64
name    : utf8
active  : bool
tags    : list<utf8>

Row 0: 1, "Ada",     true,  ["math", "code"]
Row 1: 2, "Babbage", false, ["engine"]

Performance: what you can expect

Rough numbers on a modern laptop (M-series Mac, 16 GB RAM) for a 1 GB dataset of nested user records:

The headline: Parquet wins for analytical filters because it can skip most of the file. JSONL wins for streaming, debuggability, and append-only workloads.

FAQ

— S., [email protected]