To kick off this blog, and since this is Jsoning, I'm starting with an article related to JSON, about the JSONL format 🙂
JSON is an essential format, particularly when it comes to exchanging data between applications. No need to introduce it! However, when it comes to processing large numbers of records, generating data files, or feeding processing pipelines, a standard JSON file is clearly not the most convenient format.
This is precisely the kind of need that JSONL (JSON Lines) addresses. The principle is simple: each line of the file contains an independent JSON object. This structure makes it easier to read data progressively, process it in batches, and generate it without having to load the entire document into memory.
In this article, we'll look at how JSONL works, how it differs from standard JSON, and several ways to work with it using JavaScript and common development tools (I'm trying to convince myself that it's still useful to cover this despite AI assistants. This is my denial moment).
What is the JSONL format?
JSONL, also known as JSON Lines or NDJSON (Newline Delimited JSON) — all these names don't exactly make things easier — is a text format used to store multiple independent JSON values, separated by line breaks.
Unlike a traditional JSON file, which generally uses an array to group multiple objects, JSONL places each object on a separate line.
Here's an example of a users.jsonl file:
{"id":1,"name":"Cyril","email":"cyril@example.com"}
{"id":2,"name":"Bob","email":"bob@example.com"}
{"id":3,"name":"Charlie","email":"charlie@example.com"}
Each line represents a standalone JSON document. There is no enclosing array and no commas between records. This structure has one major advantage: each record can be read and processed independently, without having to parse the entire file. A bit like CSV!
There is, however, one essential rule: each non-empty line must contain valid JSON. A line break cannot therefore arbitrarily split a JSON object across multiple lines.
JSON vs JSONL: What are the differences?
Both formats use the same JSON syntax, but their structures are different. Let's take the same data represented in both formats.
JSON format:
[
{"id":1,"name":"Cyril"},
{"id":2,"name":"Bob"},
{"id":3,"name":"Charlie"}
]
JSONL format:
{"id":1,"name":"Cyril"}
{"id":2,"name":"Bob"}
{"id":3,"name":"Charlie"}
The difference may seem minor, but it changes how the data is handled.
| Criteria | JSON | JSONL |
|---|---|---|
| Structure | Object or array | One JSON value per line |
| Separator | Commas and brackets | Line breaks |
| Progressive reading | Possible with a suitable parser | Naturally supported |
| Adding records | Requires modifying the structure | Simply adding lines |
| Batch processing | Generally requires processing the document | Each line can be processed independently |
| Common extension | .json | .jsonl or .ndjson |
JSON is particularly well suited to exchanging structured data and handling standard API responses. JSONL is useful when dealing with large amounts of data, data generated progressively, or data intended to be processed as a stream.
Why use JSONL?
JSONL addresses several practical needs encountered in software development.
1. Processing large volumes of data
With a JSON file containing several million objects in an array, a common approach is to load the entire document before accessing its records. This method can quickly become memory-intensive.
JSONL, on the other hand, allows you to process the file line by line. Each record is parsed individually, avoiding the need to keep all the data in memory. This is particularly useful for large data imports, exports, and processing tasks.
2. Storing logs and events
JSONL is well suited to logging application events. Each event is recorded on a separate line:
{"timestamp":"2026-11-20T10:15:00Z","level":"INFO","message":"Application started"}
{"timestamp":"2026-11-20T10:15:03Z","level":"WARNING","message":"Cache miss"}
{"timestamp":"2026-11-20T10:15:08Z","level":"ERROR","message":"Database connection failed"}
This makes it easy to filter, search, or aggregate events using command-line tools or scripts.
3. Feeding data pipelines
ETL (Extract, Transform, Load) pipelines often handle data coming from multiple sources.
JSONL simplifies communication between the different stages: one program can generate records, another can transform them, and a third can import them into a database. Each stage can work progressively without necessarily having to wait for the entire file to be generated.
4. Exchanging data with artificial intelligence tools
JSONL is also used in some artificial intelligence workflows, particularly when preparing datasets, training examples, or batch request files. Each line can represent an independent conversation, instruction, or example.
However, you still need to follow the schema expected by the service you're using: JSONL defines the structure of the lines, but it does not define the required fields itself.
Reading a JSONL file with JavaScript
JavaScript makes it easy to work with JSONL files. The idea is to read the content, split it into lines, and then apply JSON.parse() to each line.
Here's a simple example using Node.js:
const fs = require('fs');
const content = fs.readFileSync('users.jsonl', 'utf8');
const users = content
.split(/\r?\n/)
.filter(line => line.trim() !== '')
.map(line => JSON.parse(line));
console.log(users);
The result is a JavaScript array containing the different objects:
[
{ id: 1, name: 'Cyril', email: 'cyril@example.com' },
{ id: 2, name: 'Bob', email: 'bob@example.com' },
{ id: 3, name: 'Charlie', email: 'charlie@example.com' }
]
This method is sufficient for small to medium-sized files. However, readFileSync() loads the entire file into memory.
For large files, it's better to use a read stream.
Reading a JSONL file line by line with Node.js
The readline module allows you to process a file progressively:
const fs = require('fs');
const readline = require('readline');
async function readJsonl() {
const fileStream = fs.createReadStream('users.jsonl');
const rl = readline.createInterface({
input: fileStream,
crlfDelay: Infinity
});
for await (const line of rl) {
if (!line.trim()) {
continue;
}
try {
const user = JSON.parse(line);
console.log(user);
} catch (error) {
console.error('Invalid JSON:', line);
}
}
}
readJsonl();
This approach is better suited to large files. Lines are processed progressively, without loading the entire content into memory.
It also allows you to handle parsing errors at the individual record level, without necessarily interrupting the processing of subsequent lines.
Generating a JSONL file with JavaScript
Generating a JSONL file is relatively straightforward: you just need to convert each object into a JSON string and separate them with a newline character.
const fs = require('fs');
const users = [
{ id: 1, name: 'Cyril' },
{ id: 2, name: 'Bob' },
{ id: 3, name: 'Charlie' }
];
const jsonl = users
.map(user => JSON.stringify(user))
.join('\n');
fs.writeFileSync('users.jsonl', jsonl + '\n', 'utf8');
The generated file will contain one JSON object per line.
When generating large files, it's better to use a write stream (fs.createWriteStream) rather than building the entire string in memory.
Working with JSONL from the command line
JSONL is particularly well suited to Unix tools, mainly thanks to its line-by-line structure.
For example, the following command displays the first three entries in a file:
head -n 3 users.jsonl
To count the number of records:
wc -l users.jsonl
To filter lines containing a particular term:
grep '"name":"Cyril"' users.jsonl
You can also use jq to analyze the data.
Display names only:
jq -r '.name' users.jsonl
Count the number of records:
jq -s 'length' users.jsonl
Unlike the usual use of jq with a single JSON document, these examples take advantage of its ability to read multiple consecutive JSON values.
Conclusion
As we've seen, JSONL is a simple format, but particularly useful whenever you need to handle datasets as streams.
Its main advantage lies in its structure: each line represents an independent record. This makes it easier to generate, import, progressively process, and analyze large files.
It doesn't replace JSON, which remains perfectly suitable for many data exchanges. The two formats simply address different needs.
To experiment with the format, you can also use our online JSONL generator to easily create files containing multiple records.