wso2
Add Support for AsyncAPI 3.x.x
Problem
$Subject
Proposed Solution
We currently use apicurio-data-models [1] to parse AsyncAPI documents. We need to support 3.x.x versions as well. As per [2], it looks like apicurio-data-models have added support for AsyncAPI 3.x.x. We should check and see if upgrading apicurio-data-models would address this concern or not.
[1] https://github.com/Apicurio/apicurio-data-models [2] https://github.com/Apicurio/apicurio-data-models/issues/741#issuecomment-2625535094
Alternatives
No response
Version
No response
Progress Update - 24/10/2025
As part of the initial analysis, we reviewed the feasibility of supporting AsyncAPI 3.x.x using the Apicurio Data Models library. The current progress is summarized as follows:
Work Completed:
- Conducted a detailed analysis and review of the AsyncAPI v3 specification and its differences from v2.x.
- Reviewed the current implementation and identified version-specific logic within the Apicurio-based framework.
- Upgraded the Apicurio Data Models library to version 2.2.2.
- Updated and refactored the existing codebase to align with Apicurio 2.2.2 for AsyncAPI v2.x support.
- Performed initial backward compatibility testing with AsyncAPI v2.x.
- Verified potential UI regressions or inconsistencies following the library upgrade.
- Initiated implementation of new classes (parsers) and fields required to support AsyncAPI v3.x using Apicurio 2.2.2.
Ongoing Work:
- Resolving identified issues related to AsyncAPI v3.x support for streaming APIs.
- Conducting comprehensive end-to-end testing of streaming API flows using the updated Apicurio 2.2.2 implementation.
Progress Update
As part of improving the current validation implementation, we are attempting to leverage the Apicurio library’s built-in validation methods and rules. However, the latest version currently does not include support for validating AsyncAPI v3.x specifications. Therefore, we have raised an issue [1] with the Apicurio team to request their input and assistance on this matter.
[1]. https://github.com/Apicurio/apicurio-data-models/issues/935
Progress Update - 01/11/2025
As part of the new improvement to implement AsyncAPI v3.x support for streaming APIs, we identified several issues during basic (happy path) testing. Most of these have already been addressed or fixed. The details are as follows:
Fixed Issues
- AsyncAPI v2 Import Errors – Issues related to importing AsyncAPI v2 definitions through the Publisher Portal (e.g., protocol binding errors) have been fixed.
- General Import Errors – Multiple issues related to importing AsyncAPI definitions (such as URI template resolution) have been resolved.
- Solace API Schema Handling – The schema validation logic for Solace APIs was deprecated as part of the cleanup.
- WebSocket API (v3) Import Errors – Fixed issues in topic mapping while importing WebSocket APIs using AsyncAPI v3.
- WebSub API (v3) Import Errors – Fixed topic mapping issues during WebSub API imports.
- SSE API (v3) Import Errors – Fixed topic mapping issues during SSE API imports.
Pending Issues
- WebSocket API Creation (v3 Parser) – Currently, creating WebSocket APIs using the AsyncAPI v3 parser directly from the Publisher Portal is not functioning as expected.
- Edit/Update and Deployment for Streaming APIs (v2/v3) – Additional fixes are required to ensure that existing streaming APIs can be modified and redeployed without errors.
- Fixed: ClassCastException during scope retrieval (v2/v3).
- Fixed: NullPointerException during scope retrieval (v2).
- Pending: NullPointerException during scope retrieval (v3).
- AsyncAPI v3 Validation Logic – The validation logic for AsyncAPI v3 definitions is under development and will be finalized after internal testing and review.
Additionally minor UI inconsistencies have been identified and are currently under review. The overall functionality for importing and managing AsyncAPI v3-based streaming APIs is progressing well, with most major blockers already resolved.
Progress Update - 10/11/2025
As per the previous update, several issues were identified during initial (happy path) testing. The following progress has been made:
Fixed Issues:
- WebSocket API creation via v3 parser (Publisher Portal) — now working, minor UI fixes pending.
- Edit/Update and redeploy flow for Streaming APIs (v2/v3) — fixed.
- Scope retrieval errors resolved (ClassCastException and NPEs for v2/v3).
Pending Issue :
- AsyncAPI v3 validation logic implementation and testing.
- CLI tool validation with latest updates.
- Full end-to-end testing of Streaming API flows using Apicurio 2.2.2.
Progress Update - 20/11/2025
Recently Fixed:
- AsyncAPI v3 validation logic implementation and testing completed.
- CLI tool validated with the latest updates.
We also conducted internal code review sessions covering the new AsyncAPI parsers for both version 2 and version 3. Based on the review feedback, several improvements were made to enhance code quality, consistency, and long-term maintainability, including:
- Standardized code structure and formatting to align with internal coding guidelines.
- Improved exception handling by introducing structured API error codes and consistent exception types.
- Reduced dependency on multiple JSON processing libraries by consolidating usage to GSON where feasible.
- Refactored parsing logic to rely more on Apicurio’s native parsing mechanisms for better accuracy and future compatibility.
- Enhanced logging clarity by removing implementation-specific details and improving message consistency.
- Simplified and optimized validation flow by removing redundant logic and unnecessary type casting.
- Separated legacy and new parser logic to preserve backward compatibility while enabling cleaner v3 support.
Pending Issues:
- Adjustments to channel naming behaviour for APIs created via the Publisher.
- Completion of configuration-based validation branching.
- UI fixed and refinements.
- Comprehensive end-to-end testing to validate overall behaviour.
Progress Update - 01/12/2025
As per the previous update, we have recently completed the following:
- Adjusted channel naming behaviour for APIs created via the Publisher.
- Implemented class-level branching to support the legacy AsyncAPI v2 parser.
- Introduced TOML-based configuration to control AsyncAPI v2 parser selection.
- Added unit test cases for the AsyncAPI parsers.
- Performed additional code optimization and cleanup based on internal code review feedback.
Pending items:
- UI fixes and refinements.
- Comprehensive end-to-end testing to validate overall behaviour.