# Compatibility

**In short:** Compatibility is how well a product exchanges information with other products and does its job while sharing an environment and resources with them. Version numbers and tolerant reading help keep interfaces working as products change.

## Explanation

Compatibility is a quality of a product defined in ISO 25010 (see the article ISO/IEC 25010 Product Quality Model). It has two parts. A product should exchange information with other products. It should also perform its required functions while sharing the same environment and resources with them.

**Where it matters**

Compatibility shows up where two products meet. If one side changes, the other side may stop working. Compatibility is the property that limits this damage.

**Versioning as a signal**

Semantic versioning is a numbering scheme that writes compatibility into the version number of a public API:

- A major bump means the API changed in a backward incompatible way.
- A minor bump means new, backward compatible functionality was added.
- A patch bump means only backward compatible bug fixes were made.

A consumer can read the number and judge the risk of an upgrade.

**Reading data tolerantly**

The Tolerant Reader tactic puts some of the effort on the consumer. The consumer reads service data tolerantly, so the provider can evolve without breaking it. In practice, the consumer takes only the elements it needs and ignores the rest. Then the provider can add new elements without breaking that consumer.

**Contract tests**

A consumer can also send its reader and the reader's tests to the provider. The provider runs them in its own build. A breaking change then fails the provider's build before release. This technique is called a consumer-driven contract.

## Example

A shop's order service sends order data to a shipping service. The order team adds a new gift-message field. The shipping service reads only the address and item list, so it ignores the new field and keeps working. The order team publishes the change as a minor version, because it only adds something. Later, the order team removes the address field. That change is backward incompatible, so it needs a major version.

## Trade-offs

The facts here cover mainly versioning and data reading. Each technique has a cost.

- Tolerant reading protects the consumer from additions. It does not protect against removing or changing something the consumer needs.
- Semantic versioning only helps if the provider follows its rules for the public API.
- Shared reader tests need the consumer and provider to cooperate and to run the tests in the provider's build.



## Checks

- The document states which other products a component exchanges information with, and what it shares with them.
- Public APIs use a versioning scheme in which a major bump signals incompatible changes.
- Consumers read provider data tolerantly, taking only the elements they need.
- Providers run consumer-supplied reader tests in their build to catch breaking changes.

## Related

- [Interoperability](https://arc.fuet.ch/concepts/quality-attributes/interoperability.md)
- [ISO/IEC 25010 Product Quality Model](https://arc.fuet.ch/concepts/quality-attributes/iso-iec-25010-quality-model.md)
- [ISO/IEC 25010:2023 Product Quality Model Revision](https://arc.fuet.ch/concepts/quality-attributes/iso-25010-2023-revision.md)
- [Modifiability](https://arc.fuet.ch/concepts/quality-attributes/modifiability.md)
- [Patterns for API Design](https://arc.fuet.ch/concepts/integration/patterns-for-api-design.md)
- [Architectural Tactic](https://arc.fuet.ch/concepts/tactics/architectural-tactic.md)
- [Quality Attribute Scenario](https://arc.fuet.ch/concepts/quality-attributes/quality-attribute-scenario.md)
- [Loose Coupling](https://arc.fuet.ch/concepts/principles/loose-coupling.md)

## Sources

- [Compatibility | arc42 Quality Model](https://quality.arc42.org/qualities/compatibility) — quality.arc42.org, accessed 2026-11-09
- [Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/) — semver.org, accessed 2026-11-09
- [Tolerant Reader](https://www.martinfowler.com/bliki/TolerantReader.html) — martinfowler.com, accessed 2026-11-09