Developer guide
JSONL vs CSV: When Streaming Lines Beats Tables
If your data is a flat table, CSV is hard to beat. But the moment records become logs, events or machine-learning samples, a line-oriented format with real types starts to win. JSONL — one JSON object per line — is that format. This guide shows exactly when JSONL beats CSV and when it doesn't.
Written by Benjamin Rotshtein
Updated
- Which one should I pick?
- Pick CSV for flat, homogeneous tables destined for spreadsheets or databases. Pick JSONL when records are nested, typed, appended over time, or streamed one at a time — logs, events, training sets.
- Is JSONL always bigger than CSV?
- Usually yes for flat data — keys repeat on every line. But JSONL carries types and nesting CSV simply cannot, so the size premium buys real fidelity.
- Can I convert between them safely?
- JSONL to CSV loses types and nesting unless you flatten first. CSV to JSONL is cleaner: headers become keys. Our converters handle both directions in your browser.
What is JSONL?
JSONL (JSON Lines) is a text format where each line is one self-contained JSON object. There is no enclosing array, no commas between records, and no global structure to keep in sync.
{"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}Each line is independent: you can read the first line before the millionth is written, append a line without rewriting the file, and skip a malformed line without losing the rest. That is what makes it the default format for logs, event pipelines and ML datasets.
What is CSV?
CSV (Comma-Separated Values) is a flat row-and-column format. The first row usually holds headers, every later row is a record, and every value is plain text with no types and no nesting.
ts,user,event,ok 1752900000,42,login,true 1752900001,43,page_view,true 1752900002,44,buy,true
Its simplicity is its superpower: Excel, Google Sheets, databases and 30-year-old mainframes all read it. But that simplicity has a price — no types, no nesting, and no way to represent a record that changes shape.
JSONL vs CSV — side by side
| Criterion | CSV | JSONL |
|---|---|---|
| Structure | Flat table, one shape per file | Many JSON objects, each independent |
| Data types | All text | Explicit per line (number, bool, null) |
| Nesting | Impossible without flattening | Native, arbitrary depth |
| Streaming | Line by line, flat rows | Line by line, full objects |
| Append / reuse | Append a row | Append a line |
| File size (flat data) | Smallest | Larger — keys repeat per line |
| Typical tooling | Excel, BI, databases | Logging, Spark, ML frameworks |
When JSONL wins
- Logs and events: each event is an independent record you append without rewriting the file.
- ML training datasets: frameworks like HuggingFace Datasets and Spark load JSONL/NDJSON directly.
- Streaming pipelines: read and process one line at a time with flat memory usage.
- Heterogeneous records: JSONL objects can change shape between lines; CSV rows cannot.
- Resilience: one corrupt line breaks nothing else — unlike a single JSON document.
When CSV wins
- Spreadsheets: the destination is Excel, Google Sheets or a BI tool.
- Flat, wide exports: headers are written once, so wide identical rows are dramatically smaller.
- Databases: bulk imports into PostgreSQL, MySQL, ERPs and legacy systems.
- Human editing: someone needs to open and edit the file by hand.
The cost of JSONL: keys on every line
The main downside of JSONL is repetition. A 12-column flat record repeats all 12 key names on every single line. For a 200,000-row export that easily pushes the file 2-3x larger than the equivalent CSV — the same trade-off as JSON vs CSV. You pay in bytes and gain types, nesting and streaming.
Converting between JSONL and CSV
CSV to JSONL. Headers become keys and each row becomes one JSON object on its own line. Watch the classic traps: quoted fields can contain commas (never split on a bare ,), and all CSV values start as text — decide which should be numbers or booleans.
// CSV
name,age,city
Alice,30,Berlin
// JSONL
{"name":"Alice","age":"30","city":"Berlin"}JSONL to CSV. Flatten nested fields into columns and remember everything comes out as text. The JSON to CSV converter and CSV to JSON converter on this site handle both directions correctly, right in your browser.
Frequently asked questions
Is JSONL smaller or larger than CSV?
For the same flat table, CSV is usually smaller — often 1.5-3x smaller — because it writes column names once in a header and stores values as raw text. JSONL repeats the keys on every line. The gap shrinks for narrow records and disappears entirely for nested data, which CSV cannot represent at all.
Can JSONL handle nested data that CSV cannot?
Yes. Each JSONL line is a full JSON object, so nested objects, arrays and typed values come through intact. CSV would force you to flatten nested fields into fragile columns like user.address.city or lose the structure entirely.
When should I use JSONL instead of CSV?
When records are heterogeneous, nested, or appended continuously — log files, event streams, ML training datasets and incremental exports. JSONL lets you read one line at a time, append without rewriting, and skip a corrupt line without losing the whole file.
Is JSONL the same as NDJSON?
Yes. JSONL, NDJSON (newline-delimited JSON) and JSON Lines all describe the same thing: one self-contained JSON object per line, no enclosing array. The names differ only by which spec site documents them.
Can I convert JSONL to CSV losslessly?
Only if your records are flat. Flattening nested fields into columns is reversible in theory but tedious in practice, and all JSONL values come out of CSV as text — numbers, booleans and null lose their types unless you convert them back explicitly.
Does Excel open JSONL files?
Not natively. Excel has no built-in JSONL importer. Convert JSONL to CSV first with our free converter and open the result in Excel, Google Sheets or any BI tool.