message-queueasyncapi

Is there a way to merge or subtype type references in AsyncAPI


I have an AsyncAPI document that defines a message with an existing payload type.

channels:
  onboarding-consumption:
    publish:
      operationId: publishConsumptionEvent
      summary: Notify of application usage for consumption reporting purposes.
      message:
        name: consumptionEvent
        title: Consumption Event
        headers:
          $ref: "#/components/schemas/message-header"
        correlationId:
          $ref: "#/components/correlationIds/defaultCorrelationId"
        payload:
          $ref: "#/components/schemas/consumption"
        tags:
          - name: onboarding

Effectively I want to use the same existing payload type, but I want to add additional properties to that payload type, but in a different message definition. Is there a way to subtype (and potentially override) a schema or to merge schemas? The same question would apply to header types as well.


Solution

  • it is more related to JSON Schema. JSON Schema is one of many different formats you can use in AsyncAPI to describe your message payload definition.

    In your case I believe you need allOf JSON Schema feature. More details in official docs

    Below example, I extracted from this article.

    subscriptionStatusCommon is the part that is the same in subscriptionStatusError and subscriptionStatusSuccess.

    schemas:
        subscriptionStatusError:
          allOf:
            - properties:
                errorMessage:
                  type: string
              required:
                - errorMessage
            - $ref: '#/components/schemas/subscriptionStatusCommon'
        subscriptionStatusSuccess:
          allOf:
            - properties:
                channelID:
                  type: integer
                  description: ChannelID on successful subscription, applicable to public messages only.
                channelName:
                  type: string
                  description: Channel Name on successful subscription. For payloads 'ohlc' and 'book', respective interval or depth will be added as suffix.
              required:
                - channelID
                - channelName
            - $ref: '#/components/schemas/subscriptionStatusCommon'
        subscriptionStatusCommon:
          type: object
          required:
             - event
          properties:
            event:
              type: string
              const: subscriptionStatus
            reqid:
              $ref: '#/components/schemas/reqid'
            pair:
              $ref: '#/components/schemas/pair'
            status:
              $ref: '#/components/schemas/status'
            subscription:
              required:
                - name
              type: object
              properties:
                depth:
                  $ref: '#/components/schemas/depth'
                interval:
                  $ref: '#/components/schemas/interval'
                maxratecount:
                  $ref: '#/components/schemas/maxratecount'
                name:
                  $ref: '#/components/schemas/name'
                token:
                  $ref: '#/components/schemas/token'
    

    I hope that helps.