What JSON serialization decisions in an ASP.NET Core API can become breaking contract changes, and how would you manage them?

JSON serialization as an ASP.NET Core API contract

Treats serializer naming, nulls, enums, converters, dates, references, and polymorphism as versioned client-facing behavior.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

ASP.NET Core uses System.Text.Json by default for JSON APIs, and its options shape the public wire contract. Property naming, case matching, whether null or default values are omitted, enum representation, date and time formats, number handling, custom converters, and reference behavior can all change payloads without changing an endpoint route. I expose request and response DTOs designed for the contract instead of serializing EF entities or domain graphs directly. Global options remain consistent across endpoints, while an endpoint-specific exception is rare and documented. Before changing an option or converter, I compare representative old and new payloads and treat incompatible output or newly rejected input as an API change.

Full answer below

Practice focus

System.Text.Json, MVC and minimal API options, DTO contracts, naming, null handling, enums, dates, converters, reference cycles, polymorphism, and compatibility testing.

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# response type is not the wire contract by itself. Serializer settings and converters decide what clients actually send and receive, and small defaults can become durable dependencies.
ASP.NET Core uses System.Text.Json by default for JSON APIs, and its options shape the public wire contract. Property naming, case matching, whether null or default values are omitted, enum representation, date and time formats, number handling, custom converters, and reference behavior can all change payloads without changing an endpoint route. I expose request and response DTOs designed for the contract instead of serializing EF entities or domain graphs directly. Global options remain consistent across endpoints, while an endpoint-specific exception is rare and documented. Before changing an option or converter, I compare representative old and new payloads and treat incompatible output or newly rejected input as an API change.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.

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

Serializing persistence entities and navigation graphs directly.
Changing a global naming or enum policy as if it were internal refactoring.
Fixing reference cycles by silently dropping data from every response.
Configuring controller JSON options while assuming minimal APIs use the same options.

What JSON serialization decisions in an ASP.NET Core API can become breaking contract changes, and how would you manage them?

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue practice

Go deeper

Prerequisite

Tech stacks

Skill areas

Suggest an improvement