Free API Breaking Change Detector

API evolution is inevitable — new fields, changed types, tighter constraints, deprecated endpoints. The challenge is evolving your API without breaking the clients that depend on it. Our Breaking Change Detector compares two versions of a JSON Schema or OpenAPI specification and categorizes every difference as breaking, non-breaking, or warning, with clear explanations and remediation guidance. It runs entirely in your browser with no data leaving your machine.

What Makes a Change "Breaking"?

A breaking change is any modification that can cause existing, correctly-behaving clients to fail. The most common breaking changes in API schemas are: adding a new required property (existing clients won't send it, causing validation failures), removing a property (clients expecting it will receive null or undefined), changing a property's type (a client parsing a string field will fail if it becomes a number), removing an enum value (clients using that value will be rejected), and making constraints more restrictive (increasing minimum, decreasing maximum, adding a stricter pattern).

These changes are insidious because they can pass all your tests — your tests use the new schema — while silently breaking every deployed client. The Breaking Change Detector catches these before they reach production.

Non-Breaking Changes: Safe API Evolution

Not all changes break clients. Adding an optional property is safe — existing clients simply ignore it. Adding a new enum value is safe — existing clients use a subset of values that remain valid. Making a required property optional is safe — clients already send it. Relaxing constraints (decreasing minimum, increasing maximum, removing a pattern) is safe — existing values still pass. These non-breaking changes are the building blocks of safe API evolution.

Warnings: Changes That Need Attention

Some changes fall between breaking and safe. Description changes don't affect runtime behavior but may confuse developers relying on documentation. Default value changes can alter behavior for clients that omit the field. Format changes may affect validation in strict clients. Example changes can break auto-generated test suites. Our detector flags these as warnings — they probably won't break clients, but they deserve review.

API Versioning Strategies

When you must introduce breaking changes, you need a versioning strategy. The three main approaches are URL-based versioning (/v1/users, /v2/users), header-based versioning (Accept: application/vnd.api+json;version=2), and query parameter versioning (?version=2). Each has tradeoffs: URL versioning is the most visible and cacheable but creates endpoint proliferation; header versioning keeps URLs clean but is less discoverable; query parameters are easy to implement but can interfere with caching.

Regardless of which approach you choose, the goal is the same: run old and new versions simultaneously during a migration period, giving clients time to upgrade. The Breaking Change Detector helps you plan these migrations by showing exactly what changes clients need to accommodate.

Semantic Versioning for APIs

Semantic versioning (SemVer) provides a clear framework for API version numbers: MAJOR.MINOR.PATCH. Increment MAJOR for breaking changes, MINOR for non-breaking additions, and PATCH for bug fixes and corrections that don't change the API contract. Our detector's three categories map directly to SemVer: breaking changes require a MAJOR bump, non-breaking changes are MINOR, and warnings typically fall into MINOR or PATCH depending on impact.

For APIs with many consumers, consider a more conservative approach: any change that could conceivably affect a client, even a warning-level change, gets a MINOR version bump. Reserve PATCH for pure bug fixes and documentation corrections. This gives clients confidence that PATCH updates are always safe to adopt.

Managing Breaking Changes in Practice

The best strategy is to avoid breaking changes entirely. Additive-only changes — new optional fields, new enum values, new endpoints — are always safe. When you must make a breaking change, follow this process: first, announce the deprecation with a timeline (typically 3-6 months for public APIs). Add the new version alongside the old one. Update documentation and SDKs. Monitor usage of the deprecated version. Finally, sunset the old version only after traffic drops to an acceptable level.

For internal APIs with fewer consumers, the migration window can be shorter, but the process is the same: detect, announce, migrate, sunset. The Breaking Change Detector automates the first step, giving you a complete inventory of what changed and why it matters.

Automated Change Detection in CI/CD

The most effective way to prevent accidental breaking changes is to automate detection in your CI/CD pipeline. Store your API schema in version control alongside your code, and run a breaking change check on every pull request. If the check detects breaking changes, require explicit approval from an API owner before merging. This shifts the conversation from "we accidentally broke the API" to "should we intentionally evolve the API?"

Our tool generates markdown changelogs suitable for inclusion in release notes, PR descriptions, and API documentation. Copy the changelog directly into your release workflow to keep consumers informed about every schema change.

OpenAPI Specification Support

The detector supports both plain JSON Schemas and full OpenAPI 3.x specifications. For OpenAPI specs, it compares both the endpoint definitions (paths, methods) and the component schemas. Removed endpoints and methods are flagged as breaking, new ones as non-breaking. This gives you a complete picture of API compatibility, covering both the routing layer and the data layer.

Related Tools

Build and edit OpenAPI specs with our OpenAPI Editor. Generate mock data from your schemas using the Mock Data Generator. Validate JSON data against schemas with our JSON Schema Validator. Convert between schema formats using the Schema Converter.