Breaking Change

Overview

Breaking Change is a technical interface or data-contract concept that alters an interface or behavior so existing consumers may fail, misinterpret results, or require modification to continue operating correctly. Breakage is not limited to compilation or obvious errors. A Breaking Change causes a previously conforming consumer or stored message to behave incorrectly without adaptation; version labels alone do not determine whether a change is breaking. A breaking change violates an assumption that existing consumers legitimately rely on. Examples include removing a field, changing a data type, tightening validation, renaming an endpoint, altering authentication, changing status semantics, or making an optional response value mandatory. Providers should assess compatibility, introduce a new version when needed, publish migration guidance, and maintain an overlap period.

Emergency security changes may need faster rollout, but still require explicit communication and monitored fallback planning. A response can remain syntactically valid while changing units, ordering, precision, default behavior, or lifecycle meaning. Such semantic changes are especially dangerous in payment and blockchain systems because processing may continue incorrectly. Consumer contract tests and telemetry can identify affected traffic. Testing Breaking Change should cover boundary values, dependency failure, restart recovery, and incompatible versions where they affect the workflow. Changes to Breaking Change should be tested against normal, failed, delayed, duplicate, and recovery paths that apply to the operation. For Breaking Change, identifiers and timestamps should remain stable enough to trace the technical action to its final business outcome.

Monitoring for Breaking Change should distinguish transport success, processing success, and the final external or financial result.