OpenAPI Breaking Change Checker

Compares two bounded OpenAPI 3.x contracts and produces consumer-profile-specific breaking-change findings, waivers, fingerprints, and portable CI reports. It is built for API platform teams, SDK maintainers, release and CI engineers. The main result is structured, deterministic evidence that can be consumed from the default dataset or an Apify automation.

When to use this Actor

• Block a release when declared API changes violate a consumer's severity policy.
• Track reviewed fingerprint waivers against an explicit evaluation date.
• Export the same comparison as dataset evidence, SARIF, JUnit, and Markdown.

How it works

• Validate two inline or credential-free public HTTPS OpenAPI roots and enforce fixed byte, operation, schema, reference, and finding bounds.
• Run the exactly pinned oasdiff engine with external reference resolution disabled.
• Apply the declared consumer profile and unexpired fingerprint waivers, sort findings stably, and persist all reports before charging.

The Actor validates only the declared product contract. It does not infer facts outside the supplied data or claim outcomes that the source material cannot prove.

Quick start

1. Open the Actor's Input tab or create a Task from one of the public examples.
2. Paste or adapt this bounded example.
3. Click Start and inspect the default dataset plus the output links shown on the run page.

{
  "baseline": {
    "content": {
      "openapi": "3.1.0",
      "info": {
        "title": "Widgets",
        "version": "1.0.0"
      },
      "paths": {
        "/widgets": {
          "get": {
            "responses": {
              "200": {
                "description": "OK"
              }
            }
          }
        }
      }
    }
  },
  "revision": {
    "content": {
      "openapi": "3.1.0",
      "info": {
        "title": "Widgets",
        "version": "2.0.0"
      },
      "paths": {}
    }
  },
  "consumerProfile": {
    "id": "typescript-sdk",
    "version": "1",
    "minimumLevel": "WARN",
    "severityOverrides": {}
  },
  "waivers": [],
  "evaluationDate": "2026-09-27",
  "maxSpecBytes": 2000000,
  "maxFindings": 2000,
  "engineTimeoutSecs": 30
}

Expected result: one or more removal findings, a FAIL or WARN summary according to the profile, and SARIF/JUnit/Markdown reports.

Input

The quick-start example is intentionally small. These are the material controls; the Input tab remains authoritative for the complete current schema.

Field	Purpose and format	Default	Important bounds or interaction
baseline	Previously accepted OpenAPI document supplied inline or by a permitted source, forming the compatibility reference.	No implicit default	See the Input tab for the current schema bound.
revision	Candidate OpenAPI document evaluated against baseline after bounded parsing and canonicalization.	No implicit default	See the Input tab for the current schema bound.
consumerProfile	Explicit operations, parameters, media types, and schemas a known consumer depends on; undeclared dependencies are not inferred.	No implicit default	See the Input tab for the current schema bound.
waivers	Bounded, fingerprint-specific exceptions with explicit expiry and reason; expired or non-matching entries do not suppress findings.	No implicit default	maximum items 1000
evaluationDate	Explicit date used for deterministic waiver-expiry decisions rather than the worker's wall clock.	No implicit default	See the Input tab for the current schema bound.
maxSpecBytes	Maximum bytes accepted for each OpenAPI document before parsing.	2000000	minimum 1024; maximum 2000000
maxFindings	Caps returned compatibility findings after deterministic ordering.	2000	minimum 1; maximum 2000
engineTimeoutSecs	Maximum bounded comparison-engine time; timeout fails closed without a custom completion charge.	30	minimum 1; maximum 120

Unknown top-level fields and invalid field combinations fail validation rather than being guessed.

Output

The default dataset contains typed records. The run's Output tab links the dataset and any key-value-store reports declared by the current output schema.

Field	Meaning
recordType	Identifies finding or summary evidence.
fingerprint	Stable finding identity used by reviewed waivers.
ruleId	Current dataset field.
level	Current dataset field.
effectiveLevel	Severity after the consumer profile's explicit override policy.
waived	Current dataset field.
path	Current dataset field.
operation	Current dataset field.
text	Current dataset field.
profileId	Current dataset field.
profileVersion	Current dataset field.
engineVersion	Current dataset field.
status	Current dataset field.

Representative current-schema dataset item:

{
  "recordType": "finding",
  "fingerprint": "example-stable-fingerprint",
  "ruleId": "paths-delete",
  "level": "ERR",
  "effectiveLevel": "ERR",
  "waived": false,
  "path": "/widgets",
  "operation": "GET",
  "text": "API path removed",
  "profileId": "typescript-sdk",
  "profileVersion": "1",
  "engineVersion": "1.32.1"
}

Equivalent contracts produce a valid PASS summary with no finding rows and complete empty reports.

Pricing and billing

This Actor uses PAY_PER_EVENT; platform usage is included in event prices. A charge is eligible only after the billable unit described below is durably completed. Validation failures and the non-billable failure classes in the product contract do not emit the custom completion event. The current live policy uses the same event price at every Store tier; no tier discount is active. The Apify Pricing tab is authoritative if a later approved pricing change takes effect.

Event	What triggers it	FREE	BRONZE	SILVER	GOLD	PLATINUM	DIAMOND
consumer-gate-completed	Charged once after a baseline/revision comparison completes and durable findings and reports are written.	$0.10000000	$0.10000000	$0.10000000	$0.10000000	$0.10000000	$0.10000000
apify-actor-start	Platform-managed Actor start event.	$0.00005000	$0.00005000	$0.00005000	$0.00005000	$0.00005000	$0.00005000

The Actor does not have Task-specific prices: public Tasks use this same live Actor pricing. Third-party costs are not implied; see the data and security section for external services actually contacted.

Limits and bounds

• Each root is limited to 2,000,000 UTF-8 bytes and the pair to 4,000,000 canonical JSON bytes.
• The pair is limited to 2,000 operations, 4,000 component schemas, 20,000 local references, 32 reference hops, and 2,000 findings.
• External references, private URLs, redirects, credentials, repository access, and endpoint calls are not supported.

These are product-facing limits, not targets. Use smaller inputs when you need faster feedback or simpler evidence.

Failure and edge-case behavior

• Invalid input, unsafe fetch, malformed YAML/JSON, unsupported OpenAPI version, engine error/timeout, or supported-workload breach fails closed before consumer-gate-completed.
• An empty change set is a valid PASS with summary output.
• Waivers apply only to exact stable fingerprints under the supplied evaluation date; unmatched or expired waivers do not hide findings.

Operationally:

• Keep consumer profile id/version and evaluationDate under source control for reproducible release evidence.
• Treat the Actor as declared-contract analysis; it does not test actual server behavior.

Use with Tasks and automation

Public Tasks provide reusable saved inputs for distinct supported workflows. Start with the closest Example Task, review its visible fields and scope caveat, then save your own Task for schedules or repeated runs. Do not treat an Example Task as evidence that unsupported behavior exists.

• Check an OpenAPI release for consumer breakage: Compare two safe synthetic OpenAPI contracts and produce stable JSON, SARIF, JUnit, and Markdown release evidence.
• Monitor a public OpenAPI spec for breaking drift: Compare an immutable owner-controlled public baseline with a newer public OpenAPI build to check for consumer-breaking drift in a repeatable Task run.
• Verify an approved OpenAPI breaking-change waiver: Apply an approved synthetic waiver to a known breaking OpenAPI change while preserving the finding, fingerprint, reason, and final gate evidence.

Integration and API usage

Every saved Task can be started manually, through the Apify API, or from an Apify schedule. Run-completion webhooks can notify a downstream system after output is durable. Actor-to-Actor calls should consume the typed dataset/output links instead of scraping the Store page.

• Publish REPORT_SARIF to code-scanning tools, REPORT_JUNIT to test reporting, and REPORT_MARKDOWN to release evidence.
• Use a Task per stable consumer profile and start it from CI through the Apify API.

No third-party integration is claimed unless it is named above and supported by the current product contract.

Data, privacy, and security

• Inline specifications and generated reports remain in Apify run storage under account retention settings.
• For URL input, only credential-free public HTTPS roots are contacted; no repository or OAuth credential is accepted.

Set Apify storage retention and access according to the sensitivity of your inputs and outputs. This documentation does not create legal, privacy, compliance, or security certification.

Support and known limitations

• The Actor does not call endpoints, generate SDKs, comment on pull requests, authenticate to repositories, or certify compatibility.
• Only local OpenAPI references inside each supplied root are resolved.

For support, use the Actor Issues page. Include the run ID, a minimal reproducible input with sensitive values removed, the failing record or error code, and what you expected. Do not post credentials, private source files, customer data, or full confidential payloads.