JSON Converters in System.Text.Json: A Practical Guide

When you serialise and deserialise objects in .NET, the default behaviour of System.Text.Json handles a lot of ground. It happily round-trips primitive types, collections, plain C# classes, records, and dictionaries out of the box, and it does so with allocations an order of magnitude lower than its older sibling, Newtonsoft.Json. That speed advantage has made it the default serializer for ASP.NET Core, Azure Functions, and minimal API projects, and most teams in Sydney and Melbourne fintech shops have stopped reaching for legacy libraries when a new endpoint lands.

The trouble starts when your model does not look like vanilla .NET. You may need to round-trip a Guid as a hyphenless string, accept snake_case keys from a third-party SaaS, encode decimals as fixed-precision strings, or expose a polymorphic hierarchy where the concrete type lives in a different assembly. Custom converters exist precisely for these moments, and once you understand the lifecycle they become easier to write than they look at first glance.

Why System.Text.Json reaches for custom converters

The built-in serializer is opinionated. It assumes your property names are PascalCase, your dates are ISO-8601 strings, and your enums are integers. Any deviation requires a converter, an attribute, or a naming policy. For some cases the framework gives you a shortcut: [JsonPropertyName], [JsonConverter], and JsonNamingPolicy cover most naming tweaks without code.

For anything richer, you drop down to JsonConverter<T> and override two methods. This is where teams in Brisbane and Adelaide often discover the difference between Newtonsoft, where converter authoring is forgiving and documentation is everywhere, and System.Text.Json, where the contract is stricter but the resulting code is faster. The strictness matters once you start chasing throughput on a hot path, such as an order-matching engine in a Sydney trading firm, or a routing service running on AWS out of a Perth data centre. Another reason to write converters is version tolerance. APIs evolve, and a careful converter can accept several JSON shapes for the same field, which keeps older clients from breaking when you ship a new release.

Anatomy of the JsonConverter class

Every custom converter inherits from JsonConverter<T> and overrides Read and Write. The Read method receives a Utf8JsonReader positioned at the start of the token, and you pull values out of it as bytes. The Write method receives a Utf8JsonWriter and pushes tokens into it. Neither method is allowed to throw arbitrary exceptions for well-formed JSON; if the data is wrong, throw a JsonException so the caller can surface a sensible 400 response.

You also override CanConvert(Type) when your converter lives in a non-generic base or when you register it globally on a converter factory. The factory pattern is useful when one converter handles many types, and it is the technique Microsoft recommends for enum or type-discriminated unions. A common pattern from Canberra-based government integrators is a factory that maps a CLR interface to one of several concrete converters based on a "type" discriminator, which keeps domain models clean. A subtle but important detail: Read and Write work on raw ReadOnlySpan<byte> data. That means you cannot use JsonSerializer.Deserialize from inside Read to handle sub-objects unless you carefully manage the reader state. Most production converters copy values into local variables, then finish the token, then deserialise the captured JSON separately.

Building a converter for value types

Value types, such as structs and record struct, often need the most care. Consider a Coordinate struct with latitude and longitude, both double. You want JSON like {"lat":-33.87,"lon":151.21} rather than the default nested object. A custom converter can flatten this into a single object or, if you prefer compact output, into a string like "-33.87,151.21". The implementation reads each property name with reader.ValueSpan, compares it, and writes the corresponding token. A neat trick is to declare a static JsonEncodedText for each property name once, then reuse it across writes; that avoids re-encoding the bytes for every record.

Teams handling geospatial telemetry for fleets in Western Australia have reported measurable reductions in CPU after applying this pattern across millions of events per minute. Be careful with NaN and Infinity, which JSON technically forbids. The reader surfaces them as JsonTokenType.Number, but the writer refuses to emit them. Most converters in production normalise to null or to a sentinel string before writing, which keeps your API contract predictable across client runtimes.

Tackling polymorphic JSON models

Polymorphism is one of the trickier shapes. The server emits a base type, the wire format includes a discriminator field, and the client must instantiate the right subclass. System.Text.Json ships first-class support through [JsonDerivedType], which works for closed hierarchies, but anything dynamic or external tends to need a hand-written converter. The recipe is: read the JSON into a JsonDocument or JsonElement, inspect the discriminator, then call JsonSerializer.Deserialize with the concrete type, passing back the captured element. This pattern shows up in payment processing where the same endpoint accepts cards, bank transfers, and digital wallets, and Australian neobanks operating out of Melbourne's Docklands have built similar adapters to integrate with legacy clearing systems.

If your hierarchy is wide, prefer a registry of discriminator-to-type mappings rather than a switch statement. The registry can be populated at startup through reflection, which keeps the converter small and the types discoverable. Pair the registry with a unit test that walks every concrete subtype and round-trips a sample, because polymorphism regressions are notoriously hard to catch at runtime once the discriminator field drifts out of sync with the type catalogue.

Renaming properties and handling dictionaries

Dictionaries are where most developers get their first surprise. By default, Dictionary<string, T> serialises as a JSON object with the key as the property name. That works until the key contains characters that JSON does not allow, such as dots or colons, or until you want to enforce a casing rule across thousands of keys. A custom DictionaryConverter<TValue> can walk the reader, validate or transform keys, and write a sanitised result.

For renaming in general, weigh whether a naming policy is enough before reaching for a converter. JsonNamingPolicy.SnakeCaseLower covers string -> string mappings and is zero ceremony. A converter earns its place when the rule depends on context, for example when one set of fields is PascalCase and another is lowercase, or when a property has multiple accepted aliases depending on API version. A practical technique, used in some Perth-based mining software vendors, is to keep the public C# model stable while the wire format changes behind a converter facade. The conversion code is the only place that knows the difference, and the rest of the application keeps working when the upstream contract is renamed.

Streaming large payloads and integration with event hubs

When payloads run into hundreds of megabytes, JsonSerializer.Deserialize against a string is no longer safe. The pattern is to stream Utf8JsonReader over a PipeReader, call Read on each array element, and push it downstream without ever materialising the full document. A custom converter plays well here because you can hand the reader to it directly and let it emit one logical record at a time. This shape mirrors what Azure Event Hubs expects: a stream of discrete events rather than a single batch envelope.

The same converter that flattens a nested object for HTTP can be reused on the consumer side of an event hub pipeline. If you are exploring that world, the real-time data pipeline walkthrough on the conference site shows the end-to-end shape using Event Hubs and Stream Analytics. One pitfall: do not call JsonSerializer.Deserialize inside the streaming loop with the same options, because each call spins up its own metadata cache. Instead, cache a static JsonSerializerOptions instance and reuse it. That single change often halves allocations in a streaming consumer, which matters when you are billed per throughput unit in a multi-region Australian deployment.

Testing strategies and benchmarking

A converter that ships without tests is a converter that will break in production. The minimum test surface is a round-trip: serialise a known object, deserialise it, compare. Add negative tests for malformed input, empty strings, and boundary values like DateTime.MinValue. xUnit works fine, and most teams in Australian consultancies wire these tests into a snapshot pipeline so regressions surface before merge.

Benchmarking deserves its own project. Use BenchmarkDotNet, choose realistic payloads, and compare against a baseline of Newtonsoft with the same logic. The numbers will be predictable: System.Text.Json is typically 2x to 5x faster on writes and slightly faster on reads, with far fewer allocations. That gap widens when the converter caches JsonEncodedText and reuses a static JsonSerializerOptions instance, as covered earlier. For load testing, hook the converter into k6 or NBomber and drive traffic at production-shaped volumes. A surprising number of fast-looking converters fall over once the GC kicks in under sustained pressure, and the only way to catch that is to run the test for at least ten minutes at peak rate before declaring victory.

Comparing converter strategies at a glance

Different shapes call for different strategies, and the comparison below summarises the trade-offs you can expect when picking one approach over another.