asyncapi / asyncapi/spec

Resolved AsyncAPI 3.0 specification becomes invalid when channel.servers is dereferenced

Open
#1,141 12 comments 0 reactions 0 assignees View on GitHub
❔ Question stale
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.

Image

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.