API Breaking Changes Detector & Migration Planner

Compare two OpenAPI 3.x schemas, identify breaking changes, grade client impact, and suggest migration or compatibility strategies

Paste old and new OpenAPI schemas in JSON or YAML to detect removed endpoints, request contract tightening, response field removals, and other changes likely to break generated SDKs or downstream clients.

Example Results

1 examples

Detect request contract tightening between API versions

Compare two OpenAPI specs and show which request or response changes will break existing clients

Breaking changes are grouped by impact with migration strategies.
View input parameters
{ "oldSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: false\n content:\n application/json:\n schema:\n type: object\n properties:\n name: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n name: { type: string }\n", "newSchema": "openapi: 3.0.3\npaths:\n /users:\n post:\n requestBody:\n required: true\n content:\n application/json:\n schema:\n type: object\n required: [name, role]\n properties:\n name: { type: string }\n role: { type: string }\n responses:\n \"200\":\n description: ok\n content:\n application/json:\n schema:\n type: object\n properties:\n id: { type: string }\n" }

Key Facts

Category
Developer & Web
Input Types
textarea
Output Type
html
Sample Coverage
4
API Ready
Yes

Overview

The API Breaking Changes Detector & Migration Planner is a specialized tool designed to compare two OpenAPI 3.x schemas and identify modifications that could disrupt downstream clients. By analyzing your old and new JSON or YAML specifications, it detects removed endpoints, tightened request contracts, and deleted response fields. It then generates a comprehensive HTML report grading the impact of each change alongside actionable migration strategies, ensuring safe and predictable API versioning.

When to Use

  • •Before releasing a new API version to ensure downstream clients and generated SDKs will not break.
  • •When reviewing pull requests that modify OpenAPI specifications to catch unintended contract tightening.
  • •During API migration planning to document required client-side updates and communicate them to consumers.

How It Works

  • •Paste your original OpenAPI 3.x schema (JSON or YAML) into the Old OpenAPI Schema field.
  • •Paste the updated specification into the New OpenAPI Schema field.
  • •The tool parses both schemas to perform a deep structural diff, specifically looking for removed fields, new required parameters, and type changes.
  • •Review the generated HTML report to see a graded list of breaking changes and recommended migration paths.

Use Cases

Preventing SDK generation failures by catching removed response properties before merging API updates.
Auditing third-party API updates to understand how a vendor's new version will impact your integration.
Generating changelogs and migration guides for developer portals when releasing a major API version.

Examples

1. Detecting Request Contract Tightening

Backend Developer
Background
A developer is updating a user creation endpoint to require a user role, which was previously optional.
Problem
Need to verify if making the 'role' field required and the request body mandatory will break existing integrations.
How to Use
Paste the previous OpenAPI YAML in the Old Schema field and the updated YAML with the required 'role' property in the New Schema field.
Outcome
The tool flags the new required request body and the added required 'role' field as high-impact breaking changes, suggesting a version bump or keeping the field optional.

2. Identifying Removed Response Fields

API Product Manager
Background
The team is deprecating a legacy 'name' field in the user response payload in favor of 'firstName' and 'lastName'.
Problem
Ensuring that the removal of the 'name' field is properly documented as a breaking change for API consumers.
How to Use
Input the old schema containing the 'name' response property and the new schema where it has been removed.
Outcome
The HTML report highlights the missing 'name' field in the 200 response as a breaking change and recommends a deprecation period before removal.

Try with Samples

development
Postman Collections - API Testing
Comprehensive Postman collection examples including API testing, automation scripts, environment variables, mock servers, and advanced testing patterns for REST APIs
title token api
sample
OpenAI API Samples
Comprehensive OpenAI API examples including GPT models, DALL-E image generation, embeddings, Whisper audio processing, and function calling
title token api
sample
WebGPU Graphics API
Modern graphics API for high-performance 3D graphics and GPU computing in the browser
title token api
sample
Truffle Development Suite Samples
Truffle Ethereum development framework examples including smart contracts, testing, deployment, migrations, debugging, and development workflows
keywords migration,contract,testing
sample

FAQ

What formats are supported for the schemas?

The tool accepts OpenAPI 3.x specifications in both JSON and YAML formats.

What qualifies as a breaking change?

Breaking changes include removing endpoints, deleting response fields, changing data types, or adding new required request parameters.

Does this tool validate my OpenAPI syntax?

While it parses the structure to compare them, it is designed for diffing and detecting contract changes rather than strict linting or syntax validation.

Can it detect non-breaking changes?

The primary focus is on identifying breaking changes that impact client compatibility, such as contract tightening or field removals.

Is my API schema data stored on your servers?

No, the schema comparison is processed securely in your browser or session, and your API specifications are not permanently stored.

API Documentation

Request Endpoint

POST /en/api/tools/api-breaking-changes-detector-migration-planner

Request Parameters

Parameter Name Type Required Description
oldSchema textarea No -
newSchema textarea No -

Response Format

{
  "result": "
Processed HTML content
",
  "error": "Error message (optional)",
  "message": "Notification message (optional)",
  "metadata": {
    "key": "value"
  }
}
HTML: HTML

AI MCP Documentation

Add this tool to your MCP server configuration: 

{
  "mcpServers": {
    "elysiatools-api-breaking-changes-detector-migration-planner": {
      "name": "api-breaking-changes-detector-migration-planner",
      "description": "Compare two OpenAPI 3.x schemas, identify breaking changes, grade client impact, and suggest migration or compatibility strategies",
      "baseUrl": "https://elysiatools.com/mcp/sse?toolId=api-breaking-changes-detector-migration-planner",
      "command": "",
      "args": [],
      "env": {},
      "isActive": true,
      "type": "sse"
    }
  }
}

You can chain multiple tools, e.g.: `https://elysiatools.com/mcp/sse?toolId=png-to-webp,jpg-to-webp,gif-to-webp`, max 20 tools.

If you encounter any issues, please contact us at [email protected]