OpenAPI Spec Drift Detector

Drop two OpenAPI 3.0 / 3.1 specs (JSON or YAML) and get a per-change row with a breaking flag. Run it in a PR check, a migration audit, or a nightly CI job — the change rows are made for jq filtering, Slack alerts, and PR comments.

Pure JavaScript, zero dependencies, zero network when both specs are inline.

Why this Actor

• Catches what breaks clients — added required parameters, removed 2xx responses, removed schemas, new required properties, type narrowing, enum removals.
• Trivial CI integration — diff two URLs, fail the build if any breaking === true row appears.
• No external services — works fully offline when both specs are inline strings.
• Pairs with the api-response-delta-monitor for runtime response-shape diffing.

Who it is for

• Backend / platform teams shipping a public or internal HTTP API.
• DevX / SRE maintaining API gateways that need contract CI.
• Migration projects ("what changed between v1 and v2 of our API?").
• Tech writers auto-generating change logs from openapi.yaml PRs.

What it catches

Level	Change kind	Breaking?
Path	added	no
Path	removed	yes
Operation	added / removed	yes if removed
Parameter	added	only if required: true
Parameter	removed	only if was required: true
Parameter	required-changed	yes if becomes required
Response	added	no
Response	removed	yes if 2xx
Response schema	removed	yes for 2xx
Request body	added / removed	only if removed
Request body	required-changed	yes if becomes required
Schema	added / removed	yes if removed
Schema property	type-changed (narrowing)	yes
Schema property	required-added	yes
Schema enum	value-removed	yes

Quick start

Inline JSON (the easiest first run)

{
  "oldSpec": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"X\",\"version\":\"1\"},\"paths\":{\"/users\":{\"get\":{\"parameters\":[{\"name\":\"q\",\"in\":\"query\"}],\"responses\":{\"200\":{\"description\":\"ok\"}}}}}}",
  "newSpec": "{\"openapi\":\"3.0.0\",\"info\":{\"title\":\"X\",\"version\":\"2\"},\"paths\":{\"/users\":{\"get\":{\"parameters\":[{\"name\":\"q\",\"in\":\"query\",\"required\":true}],\"responses\":{\"200\":{\"description\":\"ok\"},\"404\":{\"description\":\"no\"}}}}}}"
}

From public URLs (no API key, no auth, just a public openapi.yaml/openapi.json)

{
  "oldUrl": "https://petstore3.openapis.org/api/v3/openapi.json",
  "newUrl": "https://petstore3.openapis.org/api/v3/openapi.json"
}

Mix one inline + one URL if needed.

Output

One dataset item per detected change. Plus a SUMMARY key-value record with run-level counts.

{
  "_kind": "change",
  "kind": "param-required-changed",
  "level": "parameter",
  "path": "/users",
  "method": "get",
  "in": "query",
  "name": "q",
  "breaking": true,
  "oldValue": { "required": false },
  "newValue": { "required": true }
}

SUMMARY:

{
  "ok": true,
  "oldVersion": "3.0.0",
  "newVersion": "3.0.0",
  "changes": 2,
  "added": 1,
  "removed": 0,
  "breaking": 1
}

CI example (GitHub Actions)

- name: OpenAPI drift check
  uses: apify/apify-cli-action@v1
  with:
    command: 'apify call stellar_ballet_0bu/openapi-spec-drift-detector --input "{\"oldUrl\":\"$OLD_SPEC\",\"newUrl\":\"$NEW_SPEC\"}"'
- name: Fail on breaking changes
  run: |
    if apify call stellar_ballet_0bu/openapi-spec-drift-detector \
        --input "{\"oldUrl\":\"$OLD_SPEC\",\"newUrl\":\"$NEW_SPEC\"}" \
        --output-dataset breaking-only | jq -e '.[] | select(.breaking==true)' ; then
      echo "Breaking OpenAPI changes detected"; exit 1
    fi

Pricing / cost expectations

Default 256 MB / 1 GB, no network when specs are inline. The Actor does no fetching when both oldSpec and newSpec are provided, so a single diff run is a few hundred KB of memory and well under a second of CPU. Pay-per-event pricing is scheduled to activate after public launch.

Run locally

npm install
npm test     # 13 cases including breaking-change detection

FAQ

Does it support OpenAPI 2.0 (Swagger)? Yes — it parses any spec that starts with openapi: or swagger:. Breaking-flag logic is the same; the 2.0 → 3.0 migration is out of scope.

Does it support Swagger diff (oldUrl + newUrl)? Yes. Public URLs only, no auth, no proxy. For private specs, paste them inline.

Will it falsely flag 4xx/5xx as breaking on removal? No. Only 2xx response removals are flagged breaking — losing a 404 is usually fine. Path removals and operation removals are always breaking.

Is YAML fully supported? A pragmatic subset: top-level scalars, nested mappings, and block sequences — covers the OpenAPI 3 YAML files typically seen in CI. For exotic YAML (anchors, multi-doc, flow style), pre-convert to JSON.

Does it touch the network? Only if you provide oldUrl and/or newUrl. With both specs inline, the Actor runs fully offline.

Related Actors

• api-response-delta-monitor — runtime response-shape diffing (one URL over time, with emit-only-on-change).
• json-schema-validator — validate any JSON document against any JSON Schema.
• jsonpointer-resolver — apply RFC 6901 read / RFC 6902 patch operations.
• webhook-sig-verifier — verify Stripe / GitHub / Apify / generic HMAC webhook signatures.
• security-headers-validator — quick webops audit on a public URL.

Support

Issues / feature requests: open an issue on the Income Factory GitHub repo or message via the Apify Actor page.