JSON in C#: System.Text.Json and source generation

A booking service received {"pnr":"A1","pnr":"B2"} and stored B2. Another received {"passangers":2}, with one letter wrong, and stored a booking for no passengers. Neither raised an error, because System.Text.Json’s default options let the last duplicate win and skip a name they cannot match.

You will turn records into JSON and back, choose how names and enums are written, generate the serialisation code when the program is built, and see what the defaults let through, with the options that refuse it.

JsonSerializer turns a record into JSON and back, and the options pick the names

roundtrip.cs writes a Booking record with the default options and with the Web defaults, reads it back, and then reads JSON whose names differ in case:

// A booking record to JSON and back with System.Text.Json: the default options, the Web defaults, enums as strings,
// and a source-generated context that does the same work without reflection.
using System.Text.Json;
using System.Text.Json.Serialization;

var booking = new Booking("4521873690", 12951, new DateOnly(2026, 12, 5), Coach.ThirdAc, 2, 3430.50m, null);

// 1. Default options: property names as written in C#, enums as numbers, null kept.
Console.WriteLine($"default: {JsonSerializer.Serialize(booking)}");

// 2. The Web defaults: camelCase names, and reading that ignores case and accepts numbers in quotes.
var web = new JsonSerializerOptions(JsonSerializerDefaults.Web) { Converters = { new JsonStringEnumConverter() } };
string json = JsonSerializer.Serialize(booking, web);
Console.WriteLine($"web:     {json}");

// 3. Back again. A record compares by value, so the copy equals the original.
Booking back = JsonSerializer.Deserialize<Booking>(json, web)!;
Console.WriteLine($"round trip equal: {back == booking}");

// 4. What the Web defaults accept that the default options do not: names in another case, numbers in quotes.
string loose = """{"PNR":"4521873690","train":"12951","date":"2026-12-05","coach":"ThirdAc","passengers":2,"fare":3430.50}""";
Booking fromWeb = JsonSerializer.Deserialize<Booking>(loose, web)!;
Console.WriteLine($"web options read: pnr {fromWeb.Pnr}, train {fromWeb.Train}, coach {fromWeb.Coach}");
Booking fromDefault = JsonSerializer.Deserialize<Booking>(loose)!;
Console.WriteLine($"default options read: pnr {fromDefault.Pnr ?? "null"}, train {fromDefault.Train}, coach {fromDefault.Coach}, and no exception");
try { JsonSerializer.Deserialize<Booking>("""{"Pnr":"4521873690","Train":"12951"}"""); }
catch (JsonException e) { Console.WriteLine($"default options, \"Train\":\"12951\": JsonException: {e.Message[..e.Message.IndexOf(" Path", StringComparison.Ordinal)]}"); }

// 5. The source-generated context: the same JSON, from code the compiler wrote when it built this program.
string generated = JsonSerializer.Serialize(booking, BookingJson.Default.Booking);
Console.WriteLine($"generated: {generated}");
Console.WriteLine($"same as web: {generated == json}; back: {JsonSerializer.Deserialize(generated, BookingJson.Default.Booking) == booking}");

public enum Coach { Sleeper, ThirdAc, SecondAc, FirstAc }

public record Booking(string Pnr, int Train, DateOnly Date, Coach Coach, int Passengers, decimal Fare, string? Note);

[JsonSourceGenerationOptions(JsonSerializerDefaults.Web, UseStringEnumConverter = true)]
[JsonSerializable(typeof(Booking))]
public partial class BookingJson : JsonSerializerContext;

default: {"Pnr":"4521873690","Train":12951,"Date":"2026-12-05","Coach":1,"Passengers":2,"Fare":3430.50,"Note":null}
web:     {"pnr":"4521873690","train":12951,"date":"2026-12-05","coach":"ThirdAc","passengers":2,"fare":3430.50,"note":null}
round trip equal: True
web options read: pnr 4521873690, train 12951, coach ThirdAc
default options read: pnr null, train 0, coach Sleeper, and no exception
default options, "Train":"12951": JsonException: The JSON value could not be converted to Booking.
generated: {"pnr":"4521873690","train":12951,"date":"2026-12-05","coach":"ThirdAc","passengers":2,"fare":3430.50,"note":null}
same as web: True; back: True

The default options wrote the C# names as they are, "Pnr" and "Coach":1, the enum as a number. The Web defaults, JsonSerializerDefaults.Web, wrote camelCase, and a JsonStringEnumConverter turned the coach into "ThirdAc". The DateOnly became "2026-12-05" and the fare kept its two decimals. Reading back gave a record equal to the original, because the serializer fills a record through its constructor:

The Web defaults also read names in any case and numbers written as strings. The default options read the same JSON without an exception, and with every value missing: pnr null, train 0, since their names must match exactly; and even with the exact name, "Train":"12951" was a JsonException for them, a number in quotes. Write and read with the same options, and keep them in one static instance: the documentation advises reusing options instead of creating them for every call.

Source generation writes the serialisation code when the program is built

By default the serializer inspects your types by reflection while the program runs. A JsonSerializerContextJsonSerializerContext: A partial class that the System.Text.Json source generator fills in while the program is built, for the types named in its [JsonSerializable] attributes, so that serialising them needs no reflection. moves that work to the build: BookingJson names Booking with [JsonSerializable], and the source generator writes the code that reads and writes it:

roundtrip.cs serialised through BookingJson.Default.Booking and got the same JSON as the Web options, same as web: True. Microsoft’s documentation explains why this matters: reflection-based serialization can break Native AOT and trimmed apps, and source generation gives them the metadata at build time. The generated code is ordinary C#, compiled into your own assembly. It has two modes: metadata, which every kind of call can use, and serialization optimization, a faster path for writing only.

The default options trust the input more than a service should

System.Text.Json refuses JSON that is not well formed, but it accepts well-formed input that a careful service would not. Each risk has an option that turns it into a JsonException:

.NET 10 adds JsonSerializerOptions.Strict, a preset that turns on the first four together. Payloads of several kinds are read with [JsonPolymorphic] and [JsonDerivedType]: the JSON names its kind with a type discriminatortype discriminator: A member such as "$type": "card" in polymorphic JSON that says which derived type to create. System.Text.Json accepts only the values declared with [JsonDerivedType]. such as "$type": "card", chosen only from the list you declare.

Polymorphic payloads from an allowlist, and the failures it stops Pro: opens with a Pro, Premium or Ultimate pass

Strict input: duplicate, misspelt and missing members, nulls and depth, measured Pro: opens with a Pro, Premium or Ultimate pass

Source generation with reflection switched off, and a lab that puts it together Pro: opens with a Pro, Premium or Ultimate pass

Practise

Three ideas from the first sections of this lesson, a few questions on each: options and names, the generated context, and what the defaults accept.

Interview questions

Fresher · What does JsonSerializerDefaults.Web change?

It creates options with the settings web APIs usually expect. Property names are written in camelCase, so Pnr becomes "pnr"; names are matched without regard to case when reading, so "PNR" also fills Pnr; and numbers may be read from strings, so "12951" fills an int. Everything else stays as in the default options: enums are still numbers unless you add a string enum converter, and unknown members are still skipped.

Key takeaways

• JsonSerializer writes a record’s properties and reads it back through its constructor, and the options decide the names: the Web defaults write camelCase and read names in any case, while the default options silently miss names in another case.
• A JsonSerializerContext lets the source generator write the serialisation code at build time, which trimmed and Native AOT apps need.
• The default options accept duplicate, unknown, null and missing members; each has an option that refuses it, and polymorphic JSON chooses its type only from the kinds you list.