Mastering JSONL Files: Structure, Use Cases, and Key Advantages
A JSONL file holds one complete JSON value per line. The official documentation calls it "the JSON Lines text format, also called newline-delimited JSON." That single rule is why it streams well, why it survives partial reads, and why a spreadsheet will not open it.
What is a JSONL file?
JSON Lines is a text format for records. The specification describes it as "a convenient format for storing structured data that may be processed one record at a time."
The documentation is explicit about where it fits. It "works well with unix-style text processing tools and shell pipelines," and the page adds that "it's a great format for log files." It is also described as "a flexible format for passing messages between cooperating processes."
The contrast with plain JSON is the point. A JSON array of a million records is one value: a reader has to consume the whole thing before the structure is complete. A JSONL file of a million records is a million values, and each line stands alone.
There is a second, closely related specification. The NDJSON spec is direct about it: "there is currently no standard for transporting instances of JSON text within a stream protocol." Its stated use case is "delivering multiple instances of JSON text through streaming protocols like TCP or UNIX Pipes."
How a JSONL file is structured
The three requirements
The JSON Lines documentation lists exactly three. The first is UTF-8 encoding. It carries a caveat borrowed from JSON itself: "like the JSON standard a byte order mark (U+FEFF) must NOT be included."
The second is that each line is a valid JSON value. The page notes that "the most common values will be objects or arrays, but any JSON value is permitted." It then gives the edge case that trips people up: "null is a valid value but a blank line is not."
The third is that the line terminator is \n. Windows line endings still work. The reason given is mechanical: "this means \r\n is also supported because surrounding white space is implicitly ignored when parsing JSON values."
What must not appear inside a line
This is the constraint that makes the format work. The NDJSON specification states it as a requirement: "the JSON texts MUST NOT contain newlines or carriage returns."
A JSON value is normally allowed to span many lines with indentation. In a line-delimited file it cannot, because the newline is the record separator. Every record has to be written on one physical line.
The final line, and empty lines
Two details differ between the two specifications, and both matter when a file is rejected.
Take the trailing newline. JSON Lines says that "including a line terminator after the last JSON value in a file is strongly recommended but not required."
On blank lines the two specs disagree. JSON Lines is strict: a blank line is not a valid value. NDJSON is permissive, allowing that "the parser MAY silently ignore empty lines," while requiring that "this behavior MUST be documented."
Extensions and media types
The naming also splits. JSON Lines says files "may be saved with the file extension .jsonl." On media type it says the "MIME type may be application/jsonl, but this is not yet standardized." NDJSON says the media type "SHOULD be application/x-ndjson" and the extension "SHOULD be .ndjson."
For compression, JSON Lines recommends stream compressors: "gzip or bzip2 are recommended for saving space, resulting in .jsonl.gz or .jsonl.bz2 files."
One small convention is worth knowing when you are reading an error message. Text editors call the first line "line 1." The documentation extends that: "the first value in a JSON Lines file should also be called 'value 1'."
What JSONL is used for
You will typically meet a .jsonl file in one of four situations.
Log and event files. The format's own documentation names log files, and the reason is that a writer can append one line at a time without rewriting anything.
Warehouse loads. Google's BigQuery documentation is a good example of the format's official standing. It supports loading "newline-delimited JSON (ndJSON) data from Cloud Storage," and its file-format picker lists the option as "JSONL (Newline delimited JSON)."
API exports of nested records. Data that will not flatten cleanly into columns keeps its nesting per line. Order lines with variable numbers of items are the classic case.
Machine learning datasets. Training and evaluation sets are commonly distributed this way, because a training loop reads records one at a time.
The common thread is streaming. It becomes the obvious choice when the file is produced incrementally or consumed incrementally.
JSONL vs JSON vs CSV
| JSONL | JSON | CSV | |
|---|---|---|---|
| Unit of the file | One value per line | One value for the whole file | One row per line |
| Nested data | Yes, per record | Yes | Not natively |
| Append a record | Add a line | Rewrite the container | Add a row |
| Partial read is useful | Yes | Rarely | Yes |
| Opens in a spreadsheet | No | No | Usually |
| Records may differ in shape | Yes | Yes | No, columns are fixed |
| Human readable in an editor | Yes, one long line each | Yes, when indented | Yes |
The row that causes the most surprise is the last-but-one. Two lines in the same JSONL file can carry different keys. That is exactly what makes the format flexible, and exactly what makes a naive import produce ragged columns.
For the column-oriented binary alternative, the Parquet explainer covers the same territory from the storage side. For the simplest tabular case, the TSV breakdown covers tab-separated text.
Key advantages
Append-only writing. A new record is a new line. Nothing earlier in the file has to change.
Streaming reads. A consumer can process record one before record two million has been written.
Failure tolerance. A truncated file is still readable up to the last complete line. A truncated JSON array is usually unreadable altogether.
Nesting survives. Structure that a CSV would have to flatten stays intact inside each record.
Shell-friendly. The documentation credits unix-style text processing and shell pipelines, because a line-oriented file works with line-oriented tools.
Warehouse support. BigQuery's documentation states the rule it enforces: "each JSON object must be on a separate line in the file."
Where JSONL stops helping
The format solves transport and appending. It does not solve any of the questions you have about the contents.
Compression is a real trade-off rather than a free win. BigQuery's documentation is blunt about the cost: "if you use gzip compression, BigQuery cannot read the data in parallel." It adds that "loading compressed JSON data into BigQuery is slower than loading uncompressed data." The format's own page recommends gzip to save space. Both are true, and they pull in opposite directions.
It is also verbose. Every line repeats every key name, so a wide record set is substantially larger than the same data in a columnar format.
And it says nothing about consistency. Records with different shapes are permitted, which means a field can quietly stop appearing halfway through a file without anything being invalid.
How to work with a JSONL file if you are not an engineer
This is the practical gap. Business tooling expects rows and columns, and a .jsonl file will not open the way a CSV does.
The pragmatic route is a conversion step. Ask whoever produced the file for a flattened CSV or Excel extract of the fields you need. Or flatten it yourself with any JSON-aware tool. You lose the nesting, which usually does not matter once you have decided which fields the analysis uses.
From there the work is ordinary analysis. Powerdrill Bloom's pricing page lists uploads for Excel, CSV, PDF, and documents, so a flattened extract goes straight in. Questions are asked in natural language rather than written as queries. The CSV AI assistant covers that path, and data connectors cover the cases where the data is better pulled from its source than exported.
The distinction worth keeping is that this is a transport decision made upstream of you. Converting away from it once the file reaches your desk is normal, not a workaround.
Conclusion
JSONL is a text format with one rule: one complete JSON value per line, and no newlines inside a value. That rule buys appendability, streaming, and partial-read tolerance, which is why logs and warehouse loads default to it.
What it does not buy is a table. The moment the file reaches someone who needs answers rather than a pipeline, the useful next step is a flattened extract and a question.
If that is where you are, try Powerdrill Bloom with the converted file and start with turning it into a chart.
Frequently asked questions
What is a JSONL file used for?
It is used for record streams: log files, event exports, warehouse loads, and machine learning datasets. The format's documentation names log files and shell pipelines specifically. The common factor is that records are written or read one at a time.
What is the difference between JSONL and NDJSON?
They describe the same idea with different paperwork. JSON Lines uses the .jsonl extension and notes that application/jsonl is not yet standardized. NDJSON specifies .ndjson and application/x-ndjson, and it permits parsers to ignore empty lines.
Can I open a JSONL file in Excel?
Not by double-clicking it, because each line is a JSON value rather than a row of cells. The usual approach is flattening the fields you need into CSV or Excel first, or using a tool that reads the format directly.
Why can't a record span multiple lines in JSONL?
Because the newline character is the record separator. The NDJSON specification states that "the JSON texts MUST NOT contain newlines or carriage returns." Pretty-printed JSON therefore has to be collapsed onto one line per record.
Is a blank line allowed in a JSONL file?
The two specifications differ. JSON Lines states that "null is a valid value but a blank line is not." NDJSON allows a parser to silently ignore empty lines, provided that behaviour is documented.