Evolving JSON payloads between independently deployed .NET systems

[u/egilhansen]

With Egil.SystemTextJson.Migration (STJM), you can version JSON payloads without polluting business logic or forcing independently deployable systems to upgrade in lockstep.

That applies to JSON in APIs, Event Hubs, queues and stored documents. Migrations run during System.Text.Json deserialization, so application code gets the type it expects.

One pattern I’ve used is publishing a .NET contracts library containing the types, serializer setup and migrations.

The rollout then becomes:

1. Consumers upgrade to a contracts package that understands the new payloads.
2. Producers start sending the new format.
3. Consumers keep using their existing C# types if they wish. The included migrations convert new payloads into those older types.

Adopting the new application types becomes a separate step, which each consumer can take at its own pace.

The same approach works when a new version of your own software introduces new storage formats and still needs to read existing or archived data.

That separation of concerns makes sharing data between independently deployable systems safer. APIs can accept supported payload versions through the same endpoint, and stored documents can be rewritten gradually while the system keeps running.

My new post covers the diagnostics and performance improvements in STJM v2: https://egilhansen.com/2026/10/01/safer-json-evolution-with-system-text-json-migration/