AsyncAPI Diff Tool — Detect Every Change, Automatically
Compare any two AsyncAPI schemas and get a categorized report of the breaking changes, deprecations, and schema modifications it detects — in seconds.
What the Diff Engine Detects
CodeRifts walks channels and the message payloads under them, and reports the change classes that visitor emits.
Breaking Change Types
- ✕ Channel removed
- ✕ Channel operation removed (publish/subscribe, or send/receive keys on the channel)
- ✕ Message removed
- ✕ Payload field removed
- ✕ Payload field type changed
- ✕ Required field added to a payload
- ✕ Enum value removed (direction not measured for AsyncAPI)
Non-Breaking Changes
- ✓ New channel added
- ✓ New operation added
- ✓ New message added
- ✓ New optional payload field added
- ✓ New enum value added
Description updates and deprecations are not reported. AsyncAPI 3 top-level operations are diffed. send is the response side: a removed field is a break and a new required field is not. receive is the request side: a new required field is a break and a removed field is not.
Why Automated AsyncAPI Diffing Matters
Manually comparing two versions of an AsyncAPI schema is not only tedious but also highly error-prone. As event-driven architectures evolve, their schemas can grow to be very complex, with intricate relationships between channels, operations, and messages. A simple text-based diff, like the one you might see in a Git commit, is insufficient because it fails to understand the semantic meaning of the AsyncAPI structure.
Automated tooling is essential for managing this complexity. A purpose-built AsyncAPI diff tool doesn't just compare text; it parses the schema, resolves all references, and understands the hierarchical structure of the event contract. For example, removing a channel or changing a message payload is a significant breaking change, but it might appear as a minor, one-word alteration in a text file. Without an automated, semantically-aware diff, teams risk shipping breaking changes unknowingly.
How CodeRifts Performs the Diff
CodeRifts compares the message payload properties under channels in both AsyncAPI documents. Local #/ $ref pointers on a channel message or payload are inlined. External $ref, unused components, servers, bindings, traits and the top-level AsyncAPI 3 operations object are outside what it currently diffs. A payload that still has an unresolved $ref is reported as PAYLOAD_REF_UNCOMPARED (non-breaking), not compared.
Detected channel, operation, message and payload changes are labelled breaking or non-breaking. There is no deprecation class. Each breaking change contributes to a risk score. The output is the change list, the score, and a decision derived from that score.
Use Cases
CI/CD Pipelines
By incorporating CodeRifts into your Continuous Integration and Continuous Deployment (CI/CD) pipeline, you can automatically fail builds that introduce high-risk or unauthorized breaking changes. You can use our CLI or REST API to add a diff check as a required step in your deployment workflow.
Pre-Merge Checks
With the CodeRifts GitHub App, every pull request that modifies an AsyncAPI schema file gets an automatic check. A detailed comment is posted directly on the PR, showing a summary of the changes and a link to the full diff report. This enables developers and reviewers to understand the impact of their changes before they are merged.
API Versioning Strategy
Automated diffing is fundamental to a sound API versioning strategy. By understanding the nature of every change, you can make deliberate decisions about when to release a new minor version (for non-breaking, backward-compatible changes) versus a new major version (for breaking changes).
Schema Evolution Management
AsyncAPI schemas are designed to evolve, but managing these changes without impacting existing clients is crucial. CodeRifts helps you track and understand every modification, ensuring that your schema evolution is intentional and safe, preventing unexpected client-side errors.
Three Ways to Diff
In-Browser
Upload two schemas to app.coderifts.com/try and get a full report instantly. No signup required.
On Every PR
Install the GitHub App and CodeRifts automatically diffs your AsyncAPI schemas on every pull request. Zero config.
More Than a Diff — A Full Governance Report
Every diff includes risk scoring, policy enforcement, security analysis, and an auto-generated changelog — showing you what changed and why it matters.
Risk Scoring
Get an objective risk score (0-100) for every change, helping you prioritize and manage API evolution with confidence.
Policy Enforcement
Define custom policies to automatically block or warn on specific breaking changes, ensuring compliance and consistency.
Auto-Changelog
Automatically generate a human-readable changelog from your diffs, making it easy to communicate API updates to consumers.
Frequently Asked Questions
What is an AsyncAPI diff?
An AsyncAPI diff is the result of comparing two versions of an AsyncAPI schema to identify all the changes between them. Unlike a simple text diff, a proper AsyncAPI diff tool understands the structure and semantics of the schema. It can pinpoint specific changes like a removed channel, a modified operation, or a new message, and classify them as breaking or non-breaking.
How do I compare two AsyncAPI schemas?
You can compare two AsyncAPI schemas using a specialized tool like CodeRifts. You can use our free in-browser tool by simply uploading your two schema files. For a more automated workflow, you can integrate our GitHub App to get a comparison on every pull request, or use our CLI or REST API to run a comparison in your own scripts or CI/CD pipelines.
What counts as a breaking change in AsyncAPI?
A breaking change in AsyncAPI is any modification to a schema that can cause existing client applications to fail. Common examples include removing a channel, changing an operation, or removing a message. CodeRifts maintains a comprehensive list of common breaking change types that it detects automatically.
Can I use this in CI/CD?
Absolutely. Integrating AsyncAPI diffing into your CI/CD pipeline is a best practice for preventing breaking changes from reaching production. CodeRifts provides both a CLI tool and a REST API that you can easily incorporate into your existing workflows, whether you use Jenkins, GitLab CI, CircleCI, or any other automation server. You can configure your pipeline to fail a build if a high-risk breaking change is detected.
Put contract changes behind a verifiable gate
Detecting the AsyncAPI diff is the first step, not the last. CodeRifts analyzes the change, issues an authorization bound to that change set, enforces it at the merge, and leaves a receipt anyone can verify offline — without an account and without asking us. A diff tells you what moved; a grant is what lets it proceed.
Install on GitHubA diff tells you what changed. It does not tell you whether it may proceed.