OpenAPI JSON Diff & Breaking Change Checker

Review an API contract change before release. Compare an accepted OpenAPI 3.0 or 3.1 JSON specification with its proposed replacement and get a readable diff for removed endpoints, newly required inputs and selected primitive type/enum changes.

Use this when your Apify, Make, n8n or API workflow needs a stored review report with a summary, finding locations and suggested review actions. Both specifications are supplied as text; no API endpoints are called.

Base price: $0.50 per completed comparison + $0.00005 per start; platform usage included. HTML, CSV and JSON are included. The live Pricing tab shows your current price and tier discounts.

The result preview below shows the three findings from the prefilled synthetic example, so you can inspect the output before paying for a run. Run the same API change sample with the displayed Actor price.

This is a selected rule subset. compatibilityEstablished is always false; use a comprehensive compatibility checker when full compatibility analysis is required.

Quick start

1. Keep the prefilled example for a first test, or paste your accepted and proposed specs into Previous OpenAPI JSON and Current OpenAPI JSON.
2. Set Maximum total charge to $0.51 at the launch price and run the Actor.
3. Open Review report for the human-readable findings. Use JSON report for automation or CSV findings for a spreadsheet.

Both inputs are JSON strings, including when calling the Actor through an API. The default example is synthetic: it removes GET /legacy, requires the state query parameter and removes the accepted request enum value closed. It produces three potential-breaking findings.

Example result

Severity	Change	Location
Potential breaking	Existing operation removed	GET /legacy
Potential breaking	Optional parameter becomes required	GET /orders, query state
Potential breaking	Previously accepted enum value removed	GET /orders, query state

The summary reads status: potential_breaking_changes, findingsTotal: 3, and compatibilityEstablished: false. A successful run means the comparison completed; check the report status before accepting a release.

Minimal API input that removes one endpoint (one selected potential-breaking finding):

{
  "previousSpec": "{\"openapi\":\"3.1.2\",\"info\":{\"title\":\"Demo\",\"version\":\"1\"},\"paths\":{\"/legacy\":{\"get\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
  "currentSpec": "{\"openapi\":\"3.1.2\",\"info\":{\"title\":\"Demo\",\"version\":\"2\"},\"paths\":{}}"
}

Example: newly required API parameters

Find newly required API parameters before release compares two synthetic specifications for GET /inventory. The endpoint remains available, but its request contract changes:

Parameter	Change
Query warehouse	Optional becomes required
Header X-Client-Version	A new required header is added

The report contains 2 REQUEST_PARAMETER_BECAME_REQUIRED findings with potential-breaking severity and their exact locations. compatibilityEstablished remains false. This static preview makes no API calls and starts no run. Running the example uses the displayed Actor price; at base pricing, one comparison plus startup is $0.50005.

Checks

Change	Result
An existing exact path/method disappears	Potential breaking change
A request parameter or request body becomes required	Potential breaking change
A direct primitive request type/enum becomes narrower	Potential breaking change
A direct primitive response type/enum becomes wider	Potential breaking change
An operation is added	Informational
Response statuses or media-type entries disappear; response statuses appear	Review required; wildcard/default coverage and consumer behavior matter
Security requirements, servers, response metadata or parameter serialization change	Review required
Complex schemas, unsupported or unresolved references, callbacks/webhooks	Explicit coverage warning

Parameter identity uses its location and name; header names are case-insensitive. Operation-level parameters override inherited path parameters. Direct local JSON-pointer references are resolved with a maximum chain of 16 links. External documents are never fetched.

Primitive schema checks support direct type, primitive enum, and OpenAPI 3.0 nullable. They account for the fact that integers are numbers. Type/enum narrowing matters for requests; widening matters for responses. Other schema constraints are not inferred to be safe.

Outputs and automation

The default key-value store contains REPORT (JSON), report.html and findings.csv. One dataset summary is written only after these reports have been saved. The summary includes status, countsByCode, countsBySeverity, operation counts, complete finding counts, and an explicit truncation flag. compatibilityEstablished is always false.

Detailed findings contain severity, code, location, oldValue, newValue and guidance. At most 500 findings are returned; counts remain complete for the selected checks. Long displayed values are shortened to 400 characters and locations to 1,000. The HTML escapes input text and has no scripts or external assets. CSV fields are quoted and formula-like cell content is escaped.

For a release workflow, submit the accepted baseline and proposed JSON specs, poll the run to completion, then retrieve REPORT. Route potential-breaking or review findings to the API owner. Store a new baseline only after your own acceptance process; this Actor does not deploy APIs or modify specifications. Scheduling the same two unchanged specifications repeatedly does not add information.

n8n or Make release-review recipe

1. Trigger the workflow when a proposed API specification changes. Load the accepted JSON document and the proposed JSON document from your repository or storage.
2. In an Apify integration's Run an Actor action, choose fluffy_ingot/openapi-change-preflight. Map both documents as JSON strings into previousSpec and currentSpec. Set 256 MB, a 60-second timeout and a $0.51 maximum total charge at launch pricing.
3. Wait for a successful run. With an asynchronous action, poll the returned run ID; route FAILED, TIMED-OUT and ABORTED states to your workflow's error branch.
4. Read the run's default dataset summary. If status is potential_breaking_changes or review_required, create a review item in your chosen system using your own connected account. Link the run and attach the JSON or CSV report from its default key-value store.
5. Even when status is no_selected_breaking_changes, keep the wider validation and approval steps you normally use. compatibilityEstablished is always false. Update your accepted baseline only after your release process approves it.

Use the run ID as your workflow's idempotency key so retries do not create duplicate review items. These steps configure a customer-owned workflow; running this Actor does not send messages or create external tickets automatically. See Apify integrations for connector setup.

Limits and coverage

• OpenAPI 3.0.x and 3.1.x supplied as JSON text only. Swagger 2, OpenAPI 3.2, YAML and URL inputs are unsupported.
• Each input: 2 million characters, 100,000 JSON value nodes, nesting depth 40, and 1,000 detected operations. Each path/operation parameter list is capped at 100 entries; each content map at 100 media types; primitive enums at 500 values. A 200,000-step work cap also applies.
• Duplicate JSON keys, non-finite numbers and selected malformed structures fail the run. This is not complete specification validation.
• Objects, arrays, nested property requirements, allOf/oneOf/anyOf, schema formats and constraints, read/write flags, anchors, schema dialect/base-URI changes and reference siblings need separate review. Complex schemas generate coverage warnings even if unchanged.
• Exact path and media-type keys are compared. Renaming a template variable may appear as an operation removal and addition. Response-code removal alone is not classified as definitely breaking.
• Links, response headers, security-scheme definitions, callbacks and webhooks are not semantically compared. No result proves an API will work with a particular client.
• Specs are processed inside the Actor run without URL fetching. Inputs and reports are stored by Apify under your account's retention and access settings; submit only documents you are authorized to process.

Pricing and run budget

Launch pricing is $0.50 per completed comparison plus $0.00005 per Actor start, with platform usage included. One comparison produces one chargeable default dataset summary item, regardless of the number of findings. There is no custom or per-finding charge. The start event can still be charged when input validation or execution fails; the comparison event is produced only after all three reports have been saved.

Set Maximum total charge to at least $0.50005, or $0.51 for a convenient example. A $0.05 budget cannot cover a comparison at the launch price. The Actor checks the effective pay-per-event budget before preparing reports and fails clearly if no comparison event fits. Apify's current Store pricing panel is authoritative; review it before running.

Background

For support, open an issue in this Actor's Issues tab with the run ID and a small redacted reproducer. Include the expected and actual result; keep private specifications and credentials out of public issues.

The rules use a deliberately small subset of the OpenAPI 3.1.2 specification and OpenAPI 3.0.4 specification. For broader compatibility analysis, the independent oasdiff project offers many more checks. This Actor is independently implemented and is not affiliated with the OpenAPI Initiative or oasdiff.

More previews and related tools

Watch the 32-second synthetic portfolio demo for a walkthrough of the four tools. The video uses sample data.

• Shopify CSV Import Checker & Supplier Catalog Diff
• Google Merchant Feed Validator & Price Checker
• Greenhouse & Ashby Job Change Monitor