JSON is one of the most common formats for exchanging structured data in .NET applications.
Traditional JSON works well for APIs and configuration files, but processing large collections can become inconvenient when an application needs to stream records incrementally.
Consider a large dataset:
[
{ "Id": 1, "Name": "Alice" },
{ "Id": 2, "Name": "Bob" },
{ "Id": 3, "Name": "Charlie" }
]
The complete document is one JSON value.
JSON Lines, commonly called JSONL or NDJSON, takes a different approach. Each line represents an independent JSON value:
{"Id":1,"Name":"Alice"}
{"Id":2,"Name":"Bob"}
{"Id":3,"Name":"Charlie"}
This format is particularly useful for streaming pipelines, logs, data exports, batch processing, and large datasets.
.NET 11 introduces built-in JSON Lines support in System.Text.Json. Microsoft documents APIs for serializing and deserializing JSON Lines data through JsonSerializer.SerializeLines and JsonSerializer.DeserializeLines. (learn.microsoft.com)
That makes JSON Lines an interesting performance topic for .NET developers.
The important question is not simply whether JSON Lines is "faster."
The useful question is:
How does JSON Lines behave when applications serialize and process large numbers of records?
What Is JSON Lines?
JSON Lines stores one valid JSON value per line.
For example:
{"id":101,"name":"Alice","active":true}
{"id":102,"name":"Bob","active":true}
{"id":103,"name":"Charlie","active":false}
Each line can be processed independently.
This has several practical advantages.
A consumer can read:
Record 1
Record 2
Record 3
without waiting for an entire JSON array to become available.
This makes JSON Lines useful for:
Streaming data
Log processing
Large exports
ETL pipelines
Machine-learning datasets
Event processing
Batch workloads
JSON Array vs JSON Lines
The difference is easier to understand through an example.
Traditional JSON:
[
{
"id": 101,
"name": "Alice"
},
{
"id": 102,
"name": "Bob"
}
]
JSON Lines:
{"id":101,"name":"Alice"}
{"id":102,"name":"Bob"}
The two formats represent similar data but have different processing characteristics.
| Characteristic | JSON Array | JSON Lines |
|---|---|---|
| Top-level structure | One array | Multiple JSON values |
| Incremental processing | Possible but more involved | Natural |
| Streaming records | Good with streaming APIs | Designed for it |
| Human readability | Good | Good |
| Append records | Requires maintaining valid JSON | Simple |
| Large data pipelines | Useful | Particularly convenient |
| Record boundaries | JSON structure | Newline |
JSON Lines is not a replacement for normal JSON.
It is another representation optimized for record-oriented workflows.
JSON Lines Support in .NET 11
.NET 11 adds built-in APIs for JSON Lines serialization and deserialization.
A simple example is:
using System.Text.Json;
var users = new[]
{
new User(1, "Alice"),
new User(2, "Bob"),
new User(3, "Charlie")
};
using var stream = File.Create("users.jsonl");
JsonSerializer.SerializeLines(
stream,
users);
The resulting file contains one JSON object per line.
For example:
{"Id":1,"Name":"Alice"}
{"Id":2,"Name":"Bob"}
{"Id":3,"Name":"Charlie"}
Microsoft documents JSON Lines support as part of the .NET 11 System.Text.Json improvements. (learn.microsoft.com)
Defining the Model
For benchmarking, use a representative model rather than a single primitive value.
public sealed record User(
int Id,
string Name,
string Email,
bool Active);
This creates a realistic serialization workload containing:
Integer data
Strings
Boolean data
Multiple properties
For production benchmarking, the model should ideally resemble the application's actual payload.
Serializing JSON Lines
A basic serialization example:
using System.Text.Json;
var users = new[]
{
new User(
1,
"Alice",
"[email protected]",
true),
new User(
2,
"Bob",
"[email protected]",
true)
};
using var stream = File.Create("users.jsonl");
JsonSerializer.SerializeLines(
stream,
users);
The method writes each item as an individual JSON value.
This differs conceptually from:
JsonSerializer.Serialize(
stream,
users);
The latter produces one JSON array.
The JSON Lines API is explicitly designed for line-delimited values.
Deserializing JSON Lines
Reading JSON Lines is similarly straightforward:
using System.Text.Json;
using var stream =
File.OpenRead("users.jsonl");
foreach (var user in
JsonSerializer.DeserializeLines<User>(
stream))
{
Console.WriteLine(user.Name);
}
This is particularly useful when processing large files.
Instead of treating the entire dataset as one logical JSON array, the application can process the sequence of records.
Why Benchmark JSON Lines?
There are several performance questions worth investigating.
Serialization Throughput
How many records can the application serialize per second?
Memory Usage
How much memory is allocated while processing large datasets?
Streaming Behavior
Can records be processed without constructing an entire collection?
File I/O
How much of the overall time is serialization versus disk I/O?
Record Size
How does performance change when objects become larger?
These questions are more useful than a single benchmark result.
Setting Up BenchmarkDotNet
Install BenchmarkDotNet in a dedicated benchmark project:
dotnet add package BenchmarkDotNet
Then create a benchmark class:
using BenchmarkDotNet.Attributes;
[MemoryDiagnoser]
public class JsonLinesBenchmark
{
private User[] _users = [];
[Params(100, 1_000, 10_000)]
public int Count { get; set; }
[GlobalSetup]
public void Setup()
{
_users = Enumerable
.Range(1, Count)
.Select(id =>
new User(
id,
$"User{id}",
$"user{id}@example.com",
true))
.ToArray();
}
}
The Params attribute allows the same benchmark to run against different dataset sizes.
That is important because serialization behavior can change significantly as the workload grows.
Benchmark JSON Lines Serialization
A benchmark can use a memory stream to separate serialization overhead from disk performance:
[Benchmark]
public void SerializeJsonLines()
{
using var stream =
new MemoryStream();
JsonSerializer.SerializeLines(
stream,
_users);
}
This measures the serialization path without involving physical disk latency.
That distinction is important.
If the benchmark writes directly to an SSD, the result may represent:
Serialization
+
Buffering
+
Filesystem
+
Storage
rather than serialization alone.
Benchmark Traditional JSON
Create a comparable benchmark for ordinary JSON:
[Benchmark]
public void SerializeJsonArray()
{
using var stream =
new MemoryStream();
JsonSerializer.Serialize(
stream,
_users);
}
Now the experiment compares:
JSON Array
vs
JSON Lines
under the same general conditions.
However, do not interpret this as a universal apples-to-apples performance comparison.
The formats have different semantics.
JSON Lines is record-oriented, while the array representation is a single JSON value.
The appropriate choice depends on the workload.
Measure Allocations
Add:
[MemoryDiagnoser]
to the benchmark class.
Then examine:
Allocated bytes
Gen 0 collections
Gen 1 collections
Gen 2 collections
Memory behavior is especially important for large data-processing workloads.
For example:
100 records
|
v
1,000 records
|
v
10,000 records
|
v
100,000 records
A design that behaves well at 100 records may behave differently at 100,000 records.
Avoid Measuring Only Small Payloads
A common benchmark mistake is using extremely small objects.
For example:
public record Small(int Id);
This can be useful for isolating serializer overhead, but it may not represent a real production payload.
Also test a more representative object:
public sealed record Order(
long Id,
string CustomerName,
string Email,
decimal Total,
string Currency,
DateTimeOffset CreatedAt,
bool Paid);
The larger model provides a more realistic serialization workload.
Benchmark Different Record Sizes
A useful experiment includes multiple payload categories.
| Dataset | Purpose |
|---|---|
| Small | Serializer overhead |
| Medium | Typical application payload |
| Large | Throughput and allocation behavior |
| Very large | Sustained streaming behavior |
Do not assume that one payload size represents all workloads.
Streaming vs Buffering
One of the most interesting characteristics of JSON Lines is its suitability for streaming.
Suppose an application processes a large export.
A traditional approach may create a complete collection:
var users =
JsonSerializer.Deserialize<User[]>(
json);
The application then processes the resulting array.
With JSON Lines, the application can process records individually:
foreach (var user in
JsonSerializer.DeserializeLines<User>(
stream))
{
ProcessUser(user);
}
The exact memory behavior should be measured rather than assumed, but the record-oriented API makes incremental processing natural.
Benchmark End-to-End Processing
Serialization-only benchmarks are useful, but a production workload often looks like:
Join the conversation! Your thoughts help the community grow.