Guide
API Contract Change and Breaking Change Guide
A consumer-centered method for classifying structural and semantic API changes without treating an automated diff as a universal verdict.
Source review checks factual claims and examples against the listed primary references. It is not an independent security audit or a substitute for testing a specific implementation.
Related tools
Breaking is a consumer outcome
A change is breaking when a supported consumer can no longer interact correctly under the compatibility promise. The same structural change may be harmless to one consumer and disruptive to another.
Use automated findings as a review queue. Combine them with consumer inventories, generated-client behavior, server tolerance, rollout order, data semantics, and observed usage before making a release decision.
Endpoints and methods
Removing an endpoint or operation is a strong breaking signal. Replacing POST with PUT is not a rename: method semantics, caches, intermediaries, permissions, retries, and generated clients can differ.
Adding an operation is usually additive, but path-template overlap, authorization defaults, routing precedence, and client generation can create side effects. Review the gateway as well as the document.
Parameters
Removing a parameter can break clients that still send it when the server rejects unknown inputs. Adding an optional parameter is commonly additive. Adding a required parameter or changing optional to required is potentially breaking for every existing request that omits it.
Location and serialization changes matter even when name and type stay the same. Moving a value from query to header, changing explode behavior, or changing repeated-key rules alters the wire representation.
Request schemas
New required properties, narrower types, tighter bounds, shorter maximum lengths, enum narrowing, and restrictive additional-property policy are common request-breaking changes. Relaxing input acceptance is usually compatible for callers but can affect validation and security assumptions.
Null, missing, empty, and defaulted values need separate review. A default annotation does not guarantee that every server or generator mutates an absent value.
Response schemas
Response compatibility reverses some intuitions. Adding a required-looking response property is often safe for tolerant JSON consumers but can break strict deserializers or exhaustive snapshots. Removing a response property or enum value is likely to break readers that depend on it.
Adding an enum value to a response can break clients with exhaustive switches even though it expands the schema. Classify it as additive structurally and still flag consumer review.
Response codes and errors
Removing a documented response code is a compatibility signal. Adding a new failure status may be semantically breaking if clients previously treated the condition as success or handled only a fixed set.
Review media types and error bodies with status codes. Replacing application/json with application/problem+json can improve consistency but still requires consumer migration.
Authentication and authorization declarations
Adding a security requirement, changing scopes, replacing a scheme, or removing an anonymous override can block existing consumers. Removing a requirement may be additive from a client perspective but high risk from a security perspective.
OpenAPI declarations do not prove enforcement. Coordinate contract review with gateway and application policy tests.
Additive changes are not automatically harmless
- A new response enum can break exhaustive clients.
- A new property can break strict decoders.
- A new endpoint can overlap a path template.
- A new optional request value can trigger code-generation name collisions.
- A new response status can change retry or UI behavior.
- A new default can change semantics even if shape remains valid.
Structural versus semantic change
Structural diffing compares declared operations and schemas. Semantic changes can keep the same shape while changing sorting, units, precision, timezone, authorization, side effects, idempotency, pagination stability, rate limits, or meaning of a status.
Write important semantics in operation descriptions, external policy, and executable tests. An unchanged OpenAPI document is not proof of unchanged behavior.
Versioning and rollout
Choose a compatibility policy before a conflict. URL versions, headers, media types, and coordinated evolution each have tradeoffs. Semantic Versioning can communicate intent for a versioned contract artifact, but it does not itself make an HTTP API compatible.
Safe rollout may require server tolerance first, dual-read or dual-write periods, consumer telemetry, deprecation communication, contract snapshots, and delayed removal. Avoid simultaneous producer and consumer assumptions that cannot coexist.
Contract test workflow
- Archive the released contract as the diff baseline.
- Validate both documents before comparing.
- Classify strong structural signals conservatively.
- Assign each finding to affected consumers or owners.
- Generate boundary and regression tests from changed constraints.
- Run deployed tests during the compatibility window.
- Record accepted risk and removal dates.
Worked review
| Change | Initial signal | Human questions |
|---|---|---|
| Required query parameter added | Potentially breaking | Can a default preserve old calls? |
| Response enum expanded | Additive with review | Are clients exhaustive? |
| 404 response removed | Potentially breaking | Was it replaced or undocumented? |
| Security scope changed | Informational/high review | Which clients possess the new scope? |
| Description changes units | Semantic risk | Do code and tests enforce the new unit? |
Analyzer limitations
A browser-local diff cannot resolve remote references, inspect live traffic, understand every JSON Schema applicator, model custom extensions, or know consumer behavior. False positives and false negatives are possible.
Use the report to focus review, not to claim universal compatibility. Keep old and new contracts, tool version, filters, and reviewer decision with release evidence.
Compatibility checklist
- Supported consumers and versions are known.
- Removed operations and parameters have a migration plan.
- Requiredness, types, bounds, enums, and additional properties are reviewed.
- Response statuses, media types, and schemas are compared.
- Security changes have enforcement tests.
- Semantic changes are documented and tested.
- Rollout order allows old and new participants to coexist.
- Deprecations have owners and dates.
References
FAQ
Is adding a field always non-breaking?
No. Tolerant JSON consumers often ignore it, but strict decoders, snapshots, signatures, and generated models may not. Review the supported consumers.
Can OpenAPI Diff decide semantic compatibility?
No. It finds structural signals. Units, sorting, permissions, side effects, defaults, and business meaning can change without a detectable shape change.
Should every breaking change create a new URL version?
Not automatically. The compatibility policy, consumer coordination, rollout mechanism, and ability to support both behaviors determine the migration design.