Compatibility Management

Manage how old and new versions interact so change does not break dependent systems or users.

Solution archetype #

185

Problem family

Composition, Interface & Interoperability Failure

Problem subfamily

Protocol, Schema & Encoding Incompatibility

The Diagnostic Story

Symptom: After a change that seemed local to the version owner, users and dependent systems break. Nobody can tell which version combinations are supported, which are deprecated, and which are forbidden. Legacy users are stranded while maintainers remain trapped by indefinite support obligations. Adapters, workarounds, and informal exceptions accumulate without any governing policy, and new features are blocked because there is no safe way to handle mixed-version operation.

Pivot: Define compatibility rules, migration paths, deprecation policy, support windows, and explicit adapter behavior — making the relationship between old and new versions a governed design decision rather than an implicit assumption.

Resolution: Breaking changes decrease and dependent actors are no longer stranded by surprise. Deprecation and end-of-support become governed events rather than accidental abandonment. Mixed-version operation during rollouts, migrations, or standard revisions becomes safer because the supported combinations are explicit and discoverable.

Reach for this when you hear…

[API platform] “We shipped v2 and half our integrators broke overnight because we did not realize they were using an undocumented behavior we removed.”

[regulatory compliance] “The new rule is in effect but the old forms are still valid for six months — we need a clear policy on what happens when an application references both.”

[medical device] “The firmware update runs fine on new hardware but the legacy implants in patients cannot accept it — we need a version matrix that is actually maintained.”

When This Archetype Applies

Partial catalog groundingSome structural conditions are represented by existing abstractions, but no sufficient condition set is fully represented.

Diagnostic problem

Different actors, systems, or components use different versions, and unmanaged version differences create failure or fragmentation.

What this problem means

The structural problem is unmanaged coexistence. Different actors, artifacts, or systems occupy different versions, but the relationship among those versions is implicit. One team may assume everyone has upgraded. Another may depend on old behavior. A third may use a transitional workaround that no one has tested. The system then fails not because any one version is incoherent, but because interaction across versions is underdesigned.

This creates several recurring symptoms: breaking changes appear as surprises, old versions become indefinite maintenance burdens, support commitments are unclear, migration is postponed until crisis, and adapters or workarounds accumulate outside governance.

Show the applicability expression

Applicability expression5 distinct conditions

Coexisting versionsandAsynchronous migration constraintsandBreaking-change riskandConflicting version assumptionsandLegacy-removal tradeoff

Algebraic1∧2∧3∧4∧5

groundedpartly groundedopen

5 conditions, all required.

5Required in every casenumbered 1–5

These hold no matter which pattern applies.

1

Coexisting versions · open

Old and new versions, rules, schemas, products, or workflows must coexist in one ecosystem. more

and — also required

2

Asynchronous migration constraints · open

Dependents cannot all migrate simultaneously because cost, timing, authority, risk, or capacity differs. more

and — also required

3

Breaking-change risk · open

A proposed version change may break existing integrations, obligations, records, workflows, expectations, or users. more

and — also required

4

Conflicting version assumptions · grounded

Different actors interpret one artifact through incompatible version assumptions. more

and — also required

5

Legacy-removal tradeoff · open

Legacy support is costly while sudden removal would cause unacceptable harm or disruption. more

Coverage

1 of 5 conditions grounded · 4 open.

Read the methodology · Download the trigger-logic data

Mechanisms / Implementations

• Adapter Layer: A thin translation layer that maps a host's calls, data, and conventions onto the interface the subsystem expects — so the subsystem can consume host capability, and later swap which host provides it, without its own code changing.
• API Versioning: Exposes a host capability as explicitly versioned interfaces that coexist, so consumers migrate on their own schedule and a change to the host never becomes a forced, simultaneous break for everyone downstream.
• Backward Compatibility Policy: Commits newer versions to keep accepting and correctly interpreting older inputs for a defined support window, degrading predictably rather than breaking when they cannot.
• Compatibility Matrix: A pairwise register of which constituents may share a domain and which must be kept apart, each verdict tied to the antagonism condition and the evidence behind it.
• Compatibility Test Suite: A maintained battery that runs the matrix of supported version, client, and configuration combinations on every change, standing guard that none of them regresses.
• Migration Guide: A dependent-facing document that turns a deprecation into something people can act on — what is going away, what replaces it, by when, and how to get an exception if they cannot move in time.
• Protocol Negotiation: Before two parties interact, they trade what versions and features each supports and settle on the best mode both can speak — dropping to a common baseline rather than failing.
• Rolling Upgrade: Rolls a new version out in small batches while the old version keeps serving, so the system runs in a safe mixed state the whole way and never has to go fully dark to change.
• Schema Migration: Transforms stored data and the interfaces over it from an old structural version to a new one — old-version dependents mapped first — so structure can change without losing or stranding information.
• Semantic Versioning: Encodes the compatibility relationship between releases into a MAJOR.MINOR.PATCH number, so a dependent can predict what will break before upgrading — without reading the diff.

▸ Show 1 more

Related Abstractions

Abstractions this archetype builds on — directly (a source ingredient) or as a related pattern. Links follow the typed catalog namespace.

Built directly on (2)

• Interoperability: Systems function together.
• Versioning: Tracks incremental changes over time.

Also references 11 related abstractions

• Accountability: Responsibility for actions.
• Adaptation: Systems adjust to conditions.
• Boundary: Defines system limits.
• Constraint: Limits possibilities to guide outcomes.
• Continuity: Smooth change without jumps.
• Coupling: Interdependence among subsystems.
• Data Integrity: Accuracy and consistency preserved.
• Fault Tolerance: Continue operating under failure.
• Indirection: Introduces intermediary references.
• Observability: Infer internal state externally.

▸ Show 1 more

Variants

Narrower or domain-specific specializations that share this archetype's core structure. Recognized variants are established; candidate variants are provisional.

Backward Compatibility Management · temporal variant · recognized

Preserves older dependents by ensuring newer versions continue to accept, interpret, or respect older interfaces, records, terms, or expectations.

Forward Compatibility Management · temporal variant · recognized

Allows older versions to tolerate or safely ignore future extensions, fields, terms, or procedures they do not yet fully understand.

Adapter-Mediated Compatibility · implementation variant · recognized

Uses an intermediary adapter, shim, crosswalk, translation layer, or compatibility wrapper to let incompatible versions interact.

Migration Window Compatibility · temporal variant · recognized

Maintains compatibility for a bounded transition period while dependents move from an old version to a new one.

Negotiated Protocol Compatibility · mechanism family variant · recognized

Uses a handshake, negotiation, or selection rule so interacting parties choose a mutually supported version or mode before proceeding.

Editorial Notes

Problem Classification

Classification: Composition, Interface & Interoperability Failure → Protocol, Schema & Encoding Incompatibility

Problem kernel: unmanaged versions fragment compatibility

Rationale: Independently used versions evolve without translation or acceptance rules, causing exchange failures and ecosystem fragmentation.

Independent corroboration: The earliest necessary condition in the frozen evidence is: Different actors, systems, or components use different versions, and unmanaged version differences create failure or fragmentation. That is a protocol schema and encoding incompatibility problem because Independently maintained formats, versions, schemas, codes, identifiers, units, and mappings cannot exchange meaning or reconstruct content reliably.

Review outcome: Independent reviewer agreement; high confidence.