Resolved AsyncAPI 3.0 specification becomes invalid when channel.servers is dereferenced
- Dominant language
- JavaScript
- Stars
- 5.3k
- Forks
- 382
- Avg merge
- 7m
- Merged PRs (30d)
- 4
Description
According to the AsyncAPI 3.0 specification, the Channel Object includes a servers property, which must be a list of references. The documentation also states:
> RECOMMENDED that parsers (or other software) dereference this property for a better development experience.
https://www.asyncapi.com/docs/reference/specification/v3.0.0#channelObject
However, in practice, when the specification is fully resolved (all $ref replaced with actual objects), the resulting document is no longer a valid AsyncAPI specification. This leads to issues such as:
The resolved spec cannot be rendered by `asyncapi-react`.
Tools expecting a valid AsyncAPI document fail because the servers property now contains objects instead of references.
Questions:
- why was this change introduced in AsyncAPI 3.0?
- is this intended behavior - that a fully dereferenced specification is not valid according to the AsyncAPI schema?
- if yes, what is the recommended approach for tools that need a resolved spec for rendering or processing?
Expected Behavior
- a resolved specification should remain valid and renderable by official AsyncAPI tools.
Contributor guide
Research direction
Start with the AsyncAPI 3.0 Channel Object definition and compare its channel.servers references with the fully dereferenced document. Reproduce the rendering failure in asyncapi-react and determine whether the specification or tool behavior is intended; done means the expected validity and recommended processing approach are clearly established.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react
- Domain
- api
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100