OpenAPI Change Preflight

Compare two OpenAPI JSON specifications before an API release. Get a readable report of removed operations, newly required request inputs, selected primitive type/enum changes and other contract changes that need review.

This is a bounded preflight for a selected rule subset. It does not establish backward compatibility or replace a full OpenAPI validator or comprehensive compatibility checker.

Quick start

1. Paste the previous specification into Previous OpenAPI JSON.
2. Paste the proposed specification into Current OpenAPI JSON.
3. Run the Actor and open Review report, JSON report, or CSV findings.

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.

{
  "previousSpec": "{\"openapi\":\"3.1.2\",\"info\":{\"title\":\"Demo\",\"version\":\"1\"},\"paths\":{}}",
  "currentSpec": "{\"openapi\":\"3.1.2\",\"info\":{\"title\":\"Demo\",\"version\":\"2\"},\"paths\":{}}"
}

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.

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

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.