API Versioning & Contract Governance: Templates and CI Checks

Compatibility rules

• Additive nullable fields are usually compatible.
• Changing enum meaning is breaking even if the schema type stays the same.
• Error contracts need the same care as success payloads.
• Deprecation windows need owner, deadline, migration guide and consumer acknowledgement.

CI check example

name: API contract checks
on: [pull_request]
jobs:
  openapi-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @redocly/cli lint openapi.yaml
      - run: npx openapi-diff baseline.yaml openapi.yaml --fail-on-incompatible