DOCUMENTATION / API COMPATIBILITY

AsyncAPI breaking changes in events and messages

By Soumik Ghosh ยท Published

Compare AsyncAPI channels, operations, and event payload revisions. Check which publishers and subscribers depend on a changed field or binding.

Remove a field that an existing subscriber expects

Before

JSON
{ "eventId": "evt_1", "orderId": "order_42" }

After

JSON
{ "eventId": "evt_1" }

If the revised event schema permits a missing orderId, older subscribers that use it for routing or reconciliation need a compatible message version or an explicit migration.

Compatibility patterns to review
Change patternDirectionClassificationClient impact
Remove a consumer-required payload fieldMessageBreakingExisting consumer validation or business logic may fail.
Rename a channel addressBindingBreaking without overlapProducers and consumers can end up on different channels.
Change the payload encodingBindingBreaking without negotiationSubscribers may be unable to decode events.
Add an optional propertyMessageReview consumersStrict consumers may reject additional properties.

What should you check before deploying?

  1. Match channel addresses and send/receive operations across both revisions.
  2. Check message headers, payload requirements, correlation IDs, and protocol bindings.
  3. Replay representative old and new messages with the real subscriber codec and retry behavior.

What can ParityDiff verify?

AsyncAPI intake captures channels, operations, payload and binding metadata. Repository impact and runtime checks depend on the configured transport and message usage.

AsyncAPI specification and the contract support matrix.

API compatibility guides and tools

Use public API change evidence in your IDE with MCP

Browse public API change history, including OpenAI and Sentry.

Rule reference