Communication

Change a message without surprising its readers

Editorial edition · 16 November 2026

The idea

Producers and consumers rarely upgrade at the same instant. A schema change therefore has a transition period in which old and new messages coexist. Design that period explicitly instead of treating deployment as an atomic event across the organisation.

Design choice

An optional field with a documented default is often easier to introduce than a renamed required field. Test actual consumer behaviour: a parser that rejects unknown properties can make an apparently additive change incompatible.

Worked example

Introduce delivery_window while still supplying the previous date field. Observe both readers before removing the older representation in a separately announced version.

Before you ship

  • Test old readers with new messages
  • Define missing and null separately
  • Set a measurable retirement condition

Examples are illustrative. Adapt the checks to your own environment.

Further reading

HTTP Semantics, RFC 9110

Search the library