AsyncAPI: $ref in examples

[JulianGarciaDev]

Hi

This is part of my asyncapi.yml:

asyncapi: 2.0.0

[...]

components:
  messages:
    expedition.create:
      headers:
        $ref: '#/components/schemas/headers'
      payload:
        $ref: '#/components/schemas/payload'
      examples:
        - headers:
            $ref: '#/components/schemas/examples.headers'
          payload:
            $ref: '#/components/schemas/examples.payload'

I would like to reference the parameters of the examples, just like I reference the general message parameters (header and payload), but it doesn't work in the examples. How should I do it? I have also tried like this, but it doesn't work:

      examples:
        - $ref: '#/components/schemas/examples.headersandpayload'

Schemas:

components:
  schemas:
    headers:
      description: Event Header
      type: object
      properties:
        eventId:
          description: Event ID
          type: string
    payload:
      description: Event Payload
      type: object
      properties:
        packageId:
          description: Package ID
          type: string
    examples.headers:
      eventId: "e66cbba1-e949-471d-ac08-66a11fbb7a41"
    examples.payload:
      packageId: "40250"
    examples.headersandpayload:
      headers:
        eventId: "e66cbba1-e949-471d-ac08-66a11fbb7a41"
      payload:
        packageId: "40250"

[lbroudoux]

Hey @JulianGdev
I think your issue is related to this one: #600
For a long time go, we have had quite an "exotic" handling of parameters in the channel names. This above issue has already been postponed and now we should tackle it in the weeks to come. Would you be around for some tests and validation?

[JulianGarciaDev]

Thank you for your answer, but I think that my issue isn't related to that one. Either way, I'd be around for some tests, sure.

[lbroudoux]

Oops... Think I read through it too quickly and you might be right: different stuff here... I'll try to have a look at it this afternoon.

[lbroudoux]

I had a detailed look at it and I think this construction is not correct from an AsyncAPI schema point of view (not from a JSON point of view).

If you have a look at Operation object definition in the specification, it says message property is either Message Object | Reference Object | Map["oneOf", [Message Object | Reference Object]]

So you can define a message this way:

channels:
  user/signedup:
    subscribe:
      message:
        headers:
          [...]
        payload:
          [...]

that way:

channels:
  user/signedup:
    subscribe:
      message:
        $ref: '#/components/messages/UserSignedUp'

of

channels:
  user/signedup:
    subscribe:
      message:
        oneof:
        - $ref: '#/components/messages/UserSignedUp'
        - $ref: '#/components/messages/RobotSignedUp'

Now, when looking the Message object definition and specially the examples property, it's says it's only [Message Example Object]

So strictly put the construction below is not valid regarding the current AsyncAPI specification.

examples:
  - $ref: '#/components/schemas/examples.headersandpayload'

As things are open and may evolve, I encourage you to start a new discussion in the AsyncAPI community that you'd like to see supported.

Cheers!

[JulianGarciaDev]

Oh! So it is not possible to reference in examples. Awkward.

Thank you very much!! You have been very helpful to me!