asyncapi / asyncapi/spec

Message referencing from operation needs to be more strict

Open
#991 29 comments 1 reaction 0 assignees View on GitHub
🐞 Bug keep-open
Dominant language
JavaScript
Stars
5.3k
Forks
382
Avg merge
7m
Merged PRs (30d)
4

Description

## Context

- Messages in operation
![Screenshot 2023-11-16 at 18 32 44](https://github.com/asyncapi/spec/assets/6995927/d2ad5569-b53e-42ff-9b79-67cbfdd9f59f)

- Messages in operation reply
![Screenshot 2023-11-16 at 18 33 29](https://github.com/asyncapi/spec/assets/6995927/ecddf219-0e0a-48ef-87f0-bad25c91f5eb)

## 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.