OpenAPI Breaking Change Detector

Compare two OpenAPI contracts before shipping a release. Find removed operations, new required inputs, type and enum changes, response-contract changes and authentication changes, with JSON-pointer evidence for every finding.

Version 1.0 • OpenAPI 3.0.0–3.0.4 only • $0.15 per successfully completed comparison. A successful comparison with zero findings is also charged $0.15. Finding count, exports and internal retries within the same run do not add charges. Platform usage is included. Invalid input and unsuccessful analysis are not charged a comparison event. Starting a separate run is a new comparison.

Quick start

The prefilled example compares two realistic Order API versions and runs without credentials or external services.

1. Paste the baseline document into oldSpec and the candidate into newSpec as JSON or YAML text strings.
2. Select old-to-new to check existing clients against the new service.
3. Run the Actor. Review both the findings and the summary counts, especially if a filter or result limit is active.
4. Download JSON, CSV and the Markdown report from Output.

Alternatively, supply oldSpecUrl and/or newSpecUrl. Clear the corresponding inline field first: exactly one source is required for each side. The inline text fields also accept a safe HTTPS document URL as their entire value. No API key is required.

Example API input (documents are strings):

{
  "oldSpec": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example\",\"version\":\"1\"},\"paths\":{\"/health\":{\"get\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
  "newSpec": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Example\",\"version\":\"2\"},\"paths\":{}}",
  "comparisonDirection": "old-to-new",
  "severityFilter": ["high", "warning", "info"],
  "maxFindings": 200
}

Comparison direction

Direction	Baseline	Target	Request check	Response check
old-to-new	oldSpec	newSpec	Previously valid requests must remain accepted	Target responses must fit baseline client expectations
new-to-old	newSpec	oldSpec	Requests built for newSpec checked against oldSpec	oldSpec responses checked against newSpec client expectations

For example, adding an enum value to a request is an expansion and normally safe under the enum rule; adding an enum value to a response can break an exhaustive client. Reversing direction reverses these roles. old_value, new_value and evidence pointers always refer to the original input documents, even in reverse mode.

Rules and severity

high = breaking under a documented rule; warning = manual review needed; info = nonbreaking under the evaluated rule. These labels are not an exploit severity rating.

Contract area	Implemented rule
Operations	Removed path/method: high. Added path/method: info. Paths are matched literally; a renamed template is treated as removal/addition.
Parameters	Merge path-level and operation-level parameters by location/name; operation overrides path-level. Added required parameter or optional→required: high. Added optional parameter: info. Removal: warning because unknown-parameter handling is not specified.
Request bodies/media	Optional→required: high. Removed accepted media type: high; added request media: info.
Types/nullability	Requests must not shrink accepted types; responses must not expand possible types. Integer is a subset of number. No coercion is assumed.
Enums	Requests must retain baseline values; responses must not add values outside baseline enum. Unconstrained and constrained enums are distinguished.
Object properties	Requests must not gain required fields; responses must preserve guaranteed fields. Project readOnly out of requests and writeOnly out of responses. Removed optional response property: warning. Adding a request property to a previously open object: warning because it can constrain previously arbitrary values.
Additional properties	Boolean open/closed changes use directional variance. Schema-valued policies and property transitions are recursively compared. Mixed boolean/schema policy changes: warning; this release does not prove all additional-property language relationships.
Bounds/arrays	minimum/maximum, length/item/property limits, exclusive bounds, uniqueItems and recursive item schemas use directional variance. Interacting constraints can require manual review.
Responses	Compare matching response media and schemas; response status additions/removals, status ranges/default coverage and response-header availability: warning.
Security	Apply global/operation override including empty security. Alternatives are OR; schemes/scopes within each alternative are AND. Each baseline credential alternative must still satisfy a target alternative. Authentication scheme definition changes: high.
Serialization/codegen	Parameter style/explode/allowReserved/allowEmptyValue, media encoding, format/pattern/multipleOf, operationId and read/write annotation changes: warning.
Composition/unsupported	allOf/oneOf/anyOf/not/discriminator and unrecognized schema keywords: warning even when unchanged. Callbacks and operation/path server routing also require review.

Local $ref values are resolved in memory with original-document evidence. Recursive object schemas are compared using active reference pairs and bounded traversal. Pure chains of references with no concrete schema, missing references and external references are rejected. OpenAPI 3.0 reference siblings are ignored, consistent with Reference Object behavior.

Inputs

Field	Meaning
oldSpec / newSpec	Inline JSON/YAML document text, or a safe HTTPS document URL
oldSpecUrl / newSpecUrl	Alternate HTTPS source; do not also provide the corresponding inline value
comparisonDirection	old-to-new (default) or new-to-old
severityFilter	Nonempty array of high, warning, info; default all three
maxFindings	1–1000; default 200

Outputs

The default Dataset contains findings with:

change_id, path, method, change_type, severity, compatibility_direction, old_value, new_value, explanation, source_pointer

Additional old_exists/new_exists flags distinguish a missing value from JSON null. source_pointer has separate old and new JSON pointers. A pointer on the absent side identifies where the value would occur; it need not exist. Resolved references point to their target definitions. Large evidence values over 4,096 characters are replaced with a marked preview; use the pointer and original document for full detail.

Key-value store exports:

• OUTPUT: filtered and limited findings in JSON, including an empty array for a clean comparison.
• OUTPUT.csv: same rows; nested values encoded as JSON, spreadsheet formula prefixes escaped.
• SUMMARY: counts before filtering/limiting, assessment, hashes, rule version, duration and truncation status.
• REPORT.md: human-readable summary report.

The limit caps returned rows, not billed events. Counts still cover the completed supported-rule analysis. Returned rows are deterministic; selection is by contract traversal, then the selected rows are sorted by severity. A filter can hide all rows while the summary still reports breaking changes. Always check SUMMARY.

Security and limits

• 2 MiB per UTF-8 document; maximum tree depth 80; 100,000 document-tree nodes.
• At most 2,000 operations per document and 30,000 schema-pair comparisons.
• 120-second analysis deadline, 100-second comparison deadline, 300-second default platform timeout.
• SafeLoader-derived YAML parser: no object constructors, aliases or merge keys; duplicate keys rejected. Boolean resolution limited to true/false; timestamp-like scalars stay strings. Integer mapping keys are normalized to strings for common YAML response codes. Quote ambiguous YAML scalars.
• HTTPS port 443 only, no credentials, query string or fragment. Only globally routable public IPs. All DNS results checked and the connection pinned to a checked IP with verified TLS and original hostname SNI.
• Redirects and compressed downloads refused; download deadline 15 seconds per document.
• No external $ref fetches. Bundle multi-file documents before submitting.
• The Actor never calls endpoints, servers, authentication URLs or callbacks described by the contracts. Only explicitly provided document URLs are downloaded.
• No proxy, AI model or third-party comparison API is used.

Input is stored in your Apify run and output contains contract excerpts. Use Apify access controls and avoid submitting credentials or secrets embedded in documents.

Scope and limitations

This is a static, explicitly bounded rule engine, not a complete OpenAPI validator, a formal proof of language inclusion, or a guarantee of actual service behavior. Structural validation rejects malformed supported inputs, but not every OpenAPI semantic rule is validated. OpenAPI 3.1, Swagger 2, external references and arbitrary JSON Schema dialects are unsupported. Documentation-only changes and unused component changes are generally omitted. Component changes matter when reachable from compared operations. Complex composition always produces review warnings; no overall runtime compatibility guarantee is made. A clean result means no breaking change was found under these supported rules, not that every client or deployment will work.

Pricing details

The only billable event is comparison-completed at $0.15, configured once per run. There are no start, per-finding or per-Dataset-row charges. Exports are produced before the event. Retry charging uses an idempotency key plus the platform's one-time-event setting; a resumed completed run reuses its checkpoint. Set a spending limit of at least $0.15. Platform usage is included in the event price. A new independently started comparison run is charged separately.

Dependencies and verification sources

Checked 2026-11-06:

• OpenAPI 3.0.4 specification
• Apify Python SDK 4.2 documentation — Apache-2.0.
• PyYAML 6.0.3 project and license — MIT; SafeLoader documentation.
• Apify pay-per-event pricing.
• Swagger Petstore official sample used for real contract testing.

Third-party license texts and the pinned dependency inventory are included in the build. The comparison engine is original AFK Digital code.