OpenAPI Consumer Breakage Gate

Turn an OpenAPI contract comparison into consumer-specific release evidence. The Actor wraps an exactly pinned oasdiff engine with versioned profiles, checked waivers, stable fingerprints, and portable JSON, SARIF, JUnit, and Markdown outputs.

Typical workflow

1. Supply baseline and revision OpenAPI 3.0, 3.1, or 3.2 documents inline or at public HTTPS URLs.
2. Name the consumer profile and choose its minimum level/explicit rule overrides. Add reviewed fingerprint waivers where necessary.
3. Run from CI, an Apify Task, API, or schedule.
4. Use the dataset for triage, OUTPUT for the verdict, and the three report records for code scanning, test reporting, and release notes.

{
    "baseline": { "url": "https://example.com/openapi-v1.json" },
    "revision": { "url": "https://example.com/openapi-v2.json" },
    "consumerProfile": {
        "id": "public-typescript-sdk",
        "version": "1",
        "minimumLevel": "WARN",
        "severityOverrides": {}
    },
    "waivers": [],
    "evaluationDate": "2026-09-16",
    "maxSpecBytes": 2000000,
    "maxFindings": 2000,
    "engineTimeoutSecs": 30
}

evaluationDate is explicit so waiver results are reproducible. Each spec must have exactly one of content or url. Cloud input accepts content as an OpenAPI object; URL content may be JSON or YAML.

Output contract

Every finding includes the oasdiff rule ID, original and profile-adjusted level, stable fingerprint, waiver status/reason, operation/path, text, profile identity, and engine version. Findings sort by fingerprint for stable output.

The verdict is:

• FAIL when an unwaived effective ERR exists;
• WARN when no error but an unwaived WARN exists;
• PASS otherwise.

Artifacts are written to REPORT_SARIF, REPORT_JUNIT, and REPORT_MARKDOWN. The default dataset view is findings.

Security and limits

The production image pins oasdiff 1.32.1 and verifies the release archive SHA-256 during build. External $ref resolution is disabled. Root URL inputs must be credential-free public HTTPS URLs, may not redirect, and may not resolve to private/reserved addresses. Specs, findings, runtime, and process output are bounded. No repository credentials or OAuth are accepted.

oasdiff is distributed under Apache-2.0. Its license is included at third_party/oasdiff-LICENSE; this Actor is not affiliated with oasdiff.

Failure behavior

Invalid configuration, YAML/JSON, OpenAPI version, unsafe fetch, engine timeout, engine error, or limit breach fails closed and produces no completed comparison event. An empty change set is a valid PASS, not an error.

Scope boundary

This Actor compares declared contracts. It does not call endpoints, test server behavior, generate SDKs, comment on pull requests, authenticate to repositories, resolve private references, or certify API compatibility. oasdiff remains free open-source software; the hosted value is the profile, waiver, evidence, and managed integration layer.

Development

npm install
set OASDIFF_PATH=C:\path\to\oasdiff.exe
npm test
npm run quality
npm run benchmark

Changelog

• 0.1.0 — Pinned oasdiff wrapper, bounded OpenAPI 3.x input, consumer profiles, waivers, deterministic findings, SARIF, JUnit, and Markdown.