← JSON Contract Diff

Check OpenAPI changes in GitHub Actions

This recipe runs the dependency-free OpenAPI Breaking Diff CLI against two JSON specifications. It fails the job when the supported checks find a breaking change and uploads a Markdown report for review.

1. Add the script

Save the core CLI as tools/openapi_breaking_diff.py and the Actions adapter as tools/openapi_diff_github.py in your repository. Commit the current production contract as contracts/openapi-baseline.json, and generate the proposed contract as openapi.json.

2. Add a workflow

name: OpenAPI compatibility

on:
  pull_request:
    paths:
      - 'openapi.json'
      - 'contracts/openapi-baseline.json'
      - 'tools/openapi_breaking_diff.py'

jobs:
  breaking-change-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Compare OpenAPI contracts
        id: diff
        continue-on-error: true
        run: |
          python3 tools/openapi_breaking_diff.py \
            contracts/openapi-baseline.json openapi.json \
            --output openapi-breaking-report.md
      - name: Upload review report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: openapi-breaking-report
          path: openapi-breaking-report.md
      - name: Enforce compatibility
        if: steps.diff.outcome == 'failure'
        run: exit 1

Exit codes

• 0: no supported breaking findings were detected.
• 2: one or more supported breaking findings were detected.
• 1: malformed input, missing file, or another input/runtime error.

Checks currently covered

• removed paths and HTTP operations;
• newly required parameters and request bodies;
• removed documented responses;
• removed response properties and changed response types;
• removed enum values;
• local JSON Pointer $ref resolution.

Need a bounded review?

The paid migration review explains consumer impact and produces an acceptance checklist. Sending a brief is only an inquiry—not an accepted order, payment, sale, or revenue. Scope is confirmed before any payment is requested.

Submit a paid task brief