How would you evolve a System.Text.Json request or response contract without surprising existing API clients?

Evolve System.Text.Json API contracts safely

Treats JSON serialization settings and DTO shape as a public contract, including naming, enums, nulls, converters, compatibility, and tests.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

I use explicit API DTOs and treat their serialized JSON shape as part of the contract. Renaming a C# property, changing camel-case policy, switching an enum between number and string, altering null omission, or tightening a converter can break clients even when the endpoint and CLR types still compile. Additive optional response fields are usually safer than removing or reinterpreting existing fields. Request changes need defaults and validation that let older payloads retain their previous meaning.

Full answer below

Practice focus

System.Text.Json, DTO contracts, property naming, enum representation, null handling, converters, compatibility, source generation, and contract tests.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Why this question matters
A C# refactor can silently become an API breaking change because serializers expose names, shapes, defaults, and conversion rules. The wire contract needs deliberate ownership separate from convenient internal models.
I use explicit API DTOs and treat their serialized JSON shape as part of the contract. Renaming a C# property, changing camel-case policy, switching an enum between number and string, altering null omission, or tightening a converter can break clients even when the endpoint and CLR types still compile. Additive optional response fields are usually safer than removing or reinterpreting existing fields. Request changes need defaults and validation that let older payloads retain their previous meaning.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
For a rename, I may keep the old wire name while changing the internal property, accept an old input name during a migration window, or introduce a new API version when the meanings cannot coexist. I define date, number, enum, polymorphism, and unknown-member behavior explicitly rather than inheriting accidental global defaults. Custom converters stay narrow and tested because they can bypass ordinary validation assumptions. Source-generated contexts can improve startup and AOT behavior, but the generated contract still requires the same compatibility review.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Assuming a CLR rename cannot affect clients.
Serializing persistence entities directly from controllers.
Changing enum or null representation globally without contract review.
Using one permissive converter to hide incompatible meanings.

How would you evolve a System.Text.Json request or response contract without surprising existing API clients?

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue practice

Go deeper

Tech stacks

Skill areas

Suggest an improvement