Compare two specifications

Backward is right for most API releases. How classification works

Paste a specification or open a file.

Paste a specification or open a file.

or press Ctrl+Enter (⌘+Enter on Mac) in either box. You can also drop a file onto a box.

Your specifications stay on your device

The comparison runs inside this browser tab, in a background worker that has no network access, and this page’s security policy blocks background network requests. Nothing you paste is uploaded or saved. $refs to other files or URLs are never followed: they are listed as not compared.

How classification works

Perspectives

  • Backward (default): can clients written for the baseline keep calling a server running the candidate? This is the usual question before a release.
  • Forward: can clients written for the candidate call a server still running the baseline? This matters during staged rollouts, when servers are rolled back, or when clients ship before servers.
  • Strict: each change is classified at the more severe of the two. Use it for APIs where clients and servers are upgraded independently.

Classes

  • Breaking: requests that worked can be rejected, or clients receive something they cannot handle.
  • Potentially breaking: safe for some clients and not others, for example a new enum value in a response.
  • Non-breaking: existing clients keep working.
  • Informational: no effect on the wire, such as descriptions or tags.
  • Unable to determine: the tool could not analyse it, for example an external $ref or a keyword such as not.

The main rules (backward perspective)

What it checks

Compared

  • Operations: added and removed, operationIds, tags, deprecation, renamed path parameters, and the OpenAPI 3.2 QUERY method and additionalOperations.
  • Parameters: added, removed, required, moved (for example query to header), serialization style, schemas, and the OpenAPI 3.2 querystring location and cookie style.
  • Request bodies and responses: status codes, content types, headers and their schemas, including OpenAPI 3.2 reusable media types and itemSchema for streamed content.
  • Schemas: types and nullability, required properties, enums, formats, defaults, limits and patterns, arrays, nested objects, additionalProperties, allOf, oneOf, anyOf and discriminators (with the OpenAPI 3.2 defaultMapping).
  • Security: requirements per operation, scopes, overrides, and changes to security schemes and OAuth flows, including OpenAPI 3.2 deprecated schemes, the device authorization flow and schemes referenced by URI.
  • Tags (OpenAPI 3.2): nesting (parent), kind and summaries, as informational changes.
  • References: local $refs, including nested and circular ones. Missing and circular references are reported.
  • Validity: malformed JSON or YAML, duplicate keys, unsupported OpenAPI versions and structural mistakes, with line numbers.

Not compared

  • External $refs to other files or URLs. They are never fetched. Bundle the spec first.
  • Your server’s actual behaviour. The tool compares what the specifications say, not what the code does.
  • Examples, links, callbacks and webhooks. Callbacks and webhooks are listed as not compared.
  • Some JSON Schema keywords (not, if/then/else, patternProperties, prefixItems and others). Changes to them are reported as “Unable to determine”.
  • Encoding and XML mappings in detail. When an OpenAPI 3.2 document is involved, changes to them are reported as “Unable to determine”.
  • Swagger 2.0 and OpenAPI 3.3 or later. OpenAPI 3.0.x, 3.1.x and 3.2.x are supported.

Questions, answered

Are my specifications uploaded?

No. Both documents are compared inside your browser tab, in a background worker that cannot make network requests. The page’s security policy blocks background requests, and nothing is saved. You can disconnect from the internet after the page has loaded and it still works.

Why is a change “potentially breaking” instead of breaking?

Some changes only break some clients. A new enum value in a response breaks a client that uses an exhaustive switch but not one that falls back to a default. Removing an optional response property breaks only clients that read it. The finding explains which clients are affected so you can decide.

My spec uses $refs to other files. What happens?

They are listed under “Unable to determine” and not compared, because the tool never reads files or URLs other than the two you provide. Bundle the spec into a single document first; most OpenAPI tools have a bundle command that inlines external references.

Does it support OpenAPI 3.2?

Yes, including 3.2.1. The QUERY method, additionalOperations, querystring parameters, cookie style, reusable media types, itemSchema, nested tags, defaultMapping, the device authorization flow and $self are validated and compared. You can also compare a 3.1 document with its 3.2 version. Callbacks and webhooks are still not compared.

Why does one schema change appear under several operations?

Compatibility depends on where a schema is used: removing a property is risky in a response but usually harmless in a request. A shared schema is therefore reported at every operation that uses it, and once under “Components”.

Is this the same as testing my API?

No. The tool compares the contracts. If your server behaves differently from its specification, only contract or integration tests against the running service will show that.

More free tools

See all free tools
  • Photos & videos
  • Use responsibly

Metadata Cleaner

Remove GPS location, device details, edit history, and AI generation details such as prompts and Content Credentials from JPEG, PNG, WebP, MP4, MOV, WebM and MKV files. No quality loss.

  • Developers
  • Free

MCP Configuration Validator

Paste your MCP server config and get the exact line of every mistake: JSON errors, wrong keys, bad args and env values, exposed secrets and client-specific problems. Works for Claude, VS Code, Cursor and Windsurf.

Need help evolving an API safely?

AICEA designs and builds APIs, integrations and the automated checks that keep them compatible.

Talk to us