Skip to content

Conversation

@h30s
Copy link

@h30s h30s commented Nov 23, 2025

Add Message-Level Versioning Support to AsyncAPI 3.0.0

This PR introduces optional name and version fields to the Message Object, enabling granular message-level versioning while maintaining full backward compatibility.

What’s Included

  • Adds name and version fields to the Message and Message Trait Objects
  • Ensures version requires name, preserving clear message identity
  • Provides spec updates, examples, and new documentation (migration guide, design doc, tests, quick reference)
  • Includes a production-grade example demonstrating multiple message versions and gradual migration

Why

AsyncAPI previously supported versioning only at the application level, causing:

  • Forced coupling of unrelated messages
  • Fragmented, ad-hoc versioning approaches
  • Limited tooling and inconsistent documentation

This change enables clear evolution of individual messages and unlocks richer tooling capabilities (diffing, timelines, compatibility checks).

Validation

  • 100% backward compatible

  • Clear validation rules:

    • name + version → ✅
    • Only name → ✅
    • Neither → ✅
    • Only version → ❌

Comprehensive tests and documentation included.

Related

Closes #1068.

Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

@sonarqubecloud
Copy link

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal to add a 'version' value into the message object to support a more granular versioning

1 participant