01 / Contract review
Name the baseline and candidate correctly
The baseline is the contract existing consumers already use; the candidate is the proposed replacement. That direction matters because removing an operation or narrowing an accepted value has a different compatibility effect from adding one.
Keep the source versions available during review. A compatibility classification is evidence for a release decision, not a substitute for understanding the affected consumer workflow.
02 / Contract review
Separate likely breaks from context-dependent changes
Review removed or newly required contract elements first, then examine changes whose effect depends on consumer behavior or runtime semantics. Compatible additions still deserve review when undocumented behavior or custom validation exists.
The comparison describes the contract it can parse. Runtime behavior, server implementation, and undocumented expectations remain outside that evidence.
- Start with removed paths, operations, parameters, properties, and enum values.
- Review new requirements and narrower types.
- Treat semantic behavior as a human review boundary.
03 / Contract review
Use machine-readable output only after reviewing the rule set
Pro batch manifests can emit JSON, JUnit, or SARIF and use process exit codes in a release check. Establish the comparison mode and acceptable findings interactively before turning the result into a gate.
Keep the same baseline direction and contract sources in local and automated workflows so the release check answers the same question each time.