Message referencing from operation needs to be more strict
- Dominant language
- JavaScript
- Stars
- 5.3k
- Forks
- 382
- Avg merge
- 7m
- Merged PRs (30d)
- 4
Description
## Context
- Messages in operation

- Messages in operation reply

## Key of the problem
```
It MUST contain a subset of the messages defined in the [channel referenced in this operation](https://github.com/asyncapi/spec/blob/next-major-spec/spec/asyncapi.md#operationObjectChannel)
```
## Confusion
but does that mean that the reference must point to a message through channel location, or can be also `components`?
for me this should be enforced:
```yaml
asyncapi: '3.0.0'
info:
title: Account Service
version: 1.0.0
description: This service is in charge of processing user signups
channels:
UserSignedUp:
messages:
UserSignedUp:
$ref: '#/components/messages/UserSigned'
operations:
user/signedup:
action: send
channel:
$ref: '#/channels/UserSignedUp'
messages:
- $ref: '#/channels/UserSignedUp/messages/UserSignedUp'
components:
messages:
UserSigned:
payload:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the user
```
this part
```
channel:
$ref: '#/channels/UserSignedUp'
messages:
- $ref: '#/channels/UserSignedUp/messages/UserSignedUp'
```
and people should not be allowed to do
```
channel:
$ref: '#/channels/UserSignedUp'
messages:
- $ref: '#/components/messages/UserSigned'
```
otherwise we'll get into a trouble of mismatch, unless I'm wrong and `messageId` is not considered to be a part of message
take this v2 example
```
asyncapi: '2.6.0'
info:
title: Account Service
version: 1.0.0
description: This service is in charge of processing user signups
channels:
user/signedup:
subscribe:
message:
$ref: '#/components/messages/UserSignedUp'
components:
messages:
UserSignedUp:
payload:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the user
```
converter will convert it to
```
asyncapi: 3.0.0
info:
title: Account Service
version: 1.0.0
description: This service is in charge of processing user signups
channels:
user/signedup:
address: user/signedup
messages:
subscribe.message:
$ref: '#/components/messages/UserSignedUp'
operations:
user/signedup.subscribe:
action: send
channel:
$ref: '#/channels/user~1signedup'
messages:
- $ref: '#/components/messages/UserSignedUp'
components:
messages:
UserSignedUp:
payload:
type: object
properties:
displayName:
type: string
description: Name of the user
email:
type: string
format: email
description: Email of the user
```
operation points to message `UserSignedUp` but on a channel level we have a message `subscribe.message`
imho the only proper way is to specify that `$ref` pointer must point to the channel - and this needs to be validated with parser of course.
Am I missing any possible errors that this could cause?
Contributor guide
Research direction
Start with the operationObjectChannel section linked in the issue and compare its wording with the AsyncAPI 3.0 examples. Resolve whether operation message references must target channel messages, then document the normative rule and identify how parser validation should enforce it; the issue does not name parser files or tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100