Optimizing JSON Response Size with System.Text.Json Source Generators

JSON is convenient, readable and well supported across modern applications, but its flexibility can create unnecessary network traffic. Repeated property names, null values, verbose identifiers and oversized nested objects all add bytes to an API response. For Australian users working across Sydney, Melbourne, Brisbane or regional areas, those bytes can affect mobile performance, cloud egress costs and perceived responsiveness.

System.Text.Json source generators help .NET applications serialize known data contracts with less runtime reflection and more predictable behaviour. They do not automatically remove fields from a payload, so the best results come from combining generated serialization metadata with carefully designed DTOs, naming policies, omission rules and HTTP compression.

Why Source Generation Matters

Traditional JSON serialization can inspect types at runtime to discover properties, constructors and converters. That reflection-based process is flexible, but it can increase startup work and memory usage. It can also make trimming and ahead-of-time deployment more difficult, which matters for containers, Azure Functions and other workloads where cold-start time is visible.

System.Text.Json source generation moves much of that metadata work to build time. A Roslyn generator produces strongly typed serialization information for the models included in a JsonSerializerContext. At runtime, the application can use that generated metadata instead of discovering the same information repeatedly.

The distinction between performance and payload size is important. A source-generated serializer may produce the same JSON shape as a reflection-based serializer. The response becomes smaller when the generated configuration is paired with decisions such as ignoring null values, using compact DTOs or avoiding unnecessary object graphs.

For a consultancy in Melbourne or a product team serving customers through the NBN and mobile networks, this separation makes performance investigations clearer. CPU savings, allocation reductions and fewer transmitted bytes are related goals, but they should be measured independently.

Design A Response Contract That Travels Light

The most effective optimisation usually happens before serialization. Returning an entity with every database column, audit field and navigation property exposes implementation details and creates a larger contract than most clients need. A response-specific DTO gives the API control over field names, nesting and optional data.

public sealed record ProductResponse(
    int Id,
    string Name,
    decimal Price,
    string Currency,
    string? ThumbnailUrl);

A product listing probably does not need a full description, supplier address, inventory history and related reviews. Those details can be provided by separate endpoints or expanded only when requested. This approach also reduces accidental circular references and makes versioning more manageable.

Property names are repeated for every item in an array, so naming decisions become significant in large collections. thumbnailUrl is clear and conventional, while an aggressively shortened name such as tu saves only a few bytes and makes the contract harder to use. Australian government and enterprise systems often need long-lived integrations, so a modest reduction should not compromise clarity or accessibility.

Flattening can help when a response contains deeply nested single-use objects, though it should reflect the domain rather than exist solely for byte reduction. Pagination, server-side filtering and field selection generally provide larger gains than micro-optimising individual property names.

Configure Generated Serialization Metadata

A source-generated context defines the types that the application serializes. The GenerationMode can be set to metadata, serialization or the default mode, depending on the .NET version and the desired balance between generated code size and runtime work.

using System.Text.Json;
using System.Text.Json.Serialization;

[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    WriteIndented = false)]
[JsonSerializable(typeof(ProductResponse))]
[JsonSerializable(typeof(IReadOnlyList<ProductResponse>))]
public partial class ApiJsonContext : JsonSerializerContext
{
}

The context can then be supplied to the serializer:

var json = JsonSerializer.Serialize(
    products,
    ApiJsonContext.Default.IReadOnlyListProductResponse);

In ASP.NET Core, generated metadata can be registered with the MVC or minimal API JSON options. The precise registration method depends on the target .NET release, but the principle remains the same: register the context and ensure the endpoint uses System.Text.Json rather than a different formatter.

WhenWritingNull is useful for optional fields such as a missing thumbnail or secondary contact number. WhenWritingDefault can remove values such as 0, false or empty defaults, but it must be applied carefully. A zero balance may be meaningful, and a false feature flag may be required by the client. Omitting a property changes the API contract, so document the behaviour and test deserialisation.

Source generation also improves trimming compatibility. That is valuable for containerised workloads running in Azure Australia East or Australia Southeast, where fast deployment and predictable memory usage can matter across many small instances.

Control Collections, Polymorphism And Converters

Large collections amplify every inefficiency. A response containing 10,000 records repeats property names 10,000 times, so pagination is often more valuable than any serializer setting. Returning 50 or 100 records per page, with stable ordering and continuation information, keeps response sizes predictable and reduces the chance of timeouts on slower connections.

Polymorphic models require extra care. If a collection contains several derived types, the serializer may need discriminators and metadata to determine each object’s shape. Those fields add bytes, while an overly broad base type can expose properties that clients do not use. Explicitly registering derived types in the source-generation context makes supported cases visible and helps avoid runtime surprises.

Custom converters are appropriate for compact representations, such as a domain value object or a fixed-format identifier. A date that always uses ISO 8601 can remain standard and interoperable; a custom converter should have a measurable purpose rather than simply making the code more clever. Shortening dates or encoding multiple values into a string can make the contract difficult for JavaScript, mobile and integration clients to consume.

For Australian businesses integrating with banks, insurers or public-sector platforms, interoperability often has greater value than shaving a few bytes from a stable field. Keep compact formats for internal or tightly controlled APIs, and use explicit versioning when a representation changes.

Compress The Bytes Sent Over HTTP

Source-generated JSON still contains text that can compress extremely well. Enable Brotli for clients that support it and gzip as a broadly compatible fallback. ASP.NET Core response compression middleware negotiates the encoding through the Accept-Encoding header, allowing browsers and mobile clients to receive an appropriate representation.

Compression is especially effective for repeated property names and similar records. A raw response of several hundred kilobytes may become a much smaller wire payload, although the exact ratio depends on values, nesting and repetition. Measure the compressed response rather than assuming that a reduction in characters equals the same reduction in network traffic.

Compression has a CPU cost. For a high-throughput API, Brotli at an aggressive quality level may consume more processing time than is justified. A balanced setting is commonly preferable for dynamic JSON, while pre-compressed static content can use a different policy. Watch server CPU, latency and response size together.

This matters for users travelling between Perth and regional Western Australia, or accessing services on congested mobile networks. It also matters financially: reducing egress from an Azure-hosted service can lower recurring costs, while a smaller payload makes APIs more forgiving when connectivity is variable.

Benchmark The Full Delivery Path

A useful benchmark compares the same DTO and data set under several configurations: reflection-based serialization, source-generated serialization, source generation with omitted nulls, and compressed HTTP delivery. Record serialization duration, allocations, raw JSON length, compressed length and end-to-end latency.

Benchmark representative data rather than a tiny example. Include records with optional fields populated and absent, long names, Unicode text, nested collections and realistic list sizes. A local test on a developer workstation will not reflect every production condition, particularly when clients are distributed across Australian cities and regional locations.

Tools such as BenchmarkDotNet can measure serializer performance in isolation. HTTP-level tests should use a representative ASP.NET Core host and inspect response headers, including Content-Encoding and Content-Length where available. For streamed or chunked responses, capture the received byte count instead of relying on a single header.

var options = new JsonSerializerOptions
{
    TypeInfoResolver = ApiJsonContext.Default
};

var payload = JsonSerializer.Serialize(
    products,
    ApiJsonContext.Default.IReadOnlyListProductResponse);

Console.WriteLine(payload.Length);

The final decision should be based on an agreed budget, such as a maximum uncompressed response size for a listing endpoint or a latency target for a mobile workflow. Source generation is valuable when it reduces runtime overhead and strengthens deployment compatibility, while DTO design, omission rules, pagination and compression determine how much data actually crosses the network.