An integration rollout can leave old and new payloads arriving together. A schema change is therefore a compatibility problem, not just a field rename in the newest application code.
Define what each field means, which versions remain supported, and how delayed or replayed events are handled. This prevents a successful deployment from turning yesterday's valid messages into today's silent data loss.
Version meaning, not only shape
A field can keep its name while changing units, allowed values, or ownership. Record those semantics in the integration contract along with required fields, optional fields, defaults, and identifiers.
Separate the external payload from the internal model where useful. A clear mapping boundary lets the application support a compatibility window without spreading provider-specific assumptions throughout the codebase.
Roll out a fictional request-status change
Suppose an external service previously sends status values open and closed. A new contract adds scheduled and cancelled, while the internal application distinguishes confirmed appointments from unconfirmed requests.
Create fixtures for every old value, every new value, a missing optional field, an unknown value, and an old event replayed after the rollout. Define whether each maps, waits for review, or is rejected with visible diagnostics. Do not silently map unknown states to open if that changes business meaning.
Test the new reader before enabling the new writer where the architecture allows it. Keep old messages processable for the agreed period. When removing compatibility code, verify that no supported sender or delayed queue still depends on the old contract.
Reconcile partial adoption and failures
An agency may have several connected client accounts that upgrade at different times. Record the active contract version per connection if needed, and avoid assuming every account changed when one provider announcement appeared.
Retain event identities and processing outcomes so a failed mapping can be repaired without duplicating the business action. Official Stripe webhook guidance is one provider-specific reference for external events; use the actual source system's versioning and replay rules for your integration.
The tradeoff is compatibility effort versus rollout flexibility. Supporting too many historical shapes indefinitely creates maintenance burden. Removing support too early creates avoidable failures. Choose a documented window, monitor remaining use, and name the owner who can approve removal.
The StackFlight case study supplies related integrated-SaaS context. The status contract is fictional and does not describe a specific provider's current payload.
Questions about schema rollouts
Is adding an optional field always harmless?
Not necessarily. Strict readers, validation, signatures, and downstream assumptions can make apparently additive changes significant. Test the actual consumers.
Should unknown values be accepted automatically?
Only under a defined safe policy. A visible review state can be preferable to assigning an incorrect business meaning.
What should be ready before switching writers?
Have compatibility fixtures, mapping decisions, version visibility, replay handling, and rollback expectations. Bring the contract matrix to an integration rollout review.