Example override for ref schema object not working

[christianrowlands]

Note: Issue #463 had two bugs mentioned in it, so I am creating this ticket to pull one of the bugs out so it can be tracked individually (my bad for lumping them together).

Describe the bug

The example that I set for a field is not being used in the generated HTML when using a $ref to a schema.

I have published my AsyncAPI HTML docs on public URL, so you can see both issues on that site.

if you look at any of the Payload schemas, they all have a messageType field. A couple months ago I noticed that the override description and example stopped working. For example, with the GSM Record under the gsm_message operation, the messageType should be The type of message, must be GsmRecord. since that is what I set it to here in the yaml spec.

In addition, the example is also not being overridden as expected. I set it to GsmRecord here in the yaml spec but in the generated doc it shows up as string. Below is a screenshot of the linked generated HTML:

How to Reproduce

For reproducing the issue, you can either use the full yaml spec I have linked to that is in my GitHub repo, or you can use this condensed version I made below. I typically use the docker container for asyncapi to generate the yaml. Something like:

docker run --rm -it -v ${PWD}/asyncapi/test.yaml:/app/test.yaml -v ${PWD}/testdoc:/app/output asyncapi/generator:1.17.0 /app/test.yaml @asyncapi/[email protected] -o /app/output --force-write

asyncapi: 2.6.0
info:
  title: Test API
  version: 0.13.1
  description: >
    A test doc for reproducing an issue
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
servers:
  mosquitto:
    url: 'mqtt://test.mosquitto.org'
    protocol: mqtt
defaultContentType: application/json
channels:
  gsm_message:
    description: >-
      The gsm_message topic/channel is where GSM survey records can be
      published. For MQTT, set the MQTT topic as "gsm_message" and then publish
      a JSON message representing a GSM survey record in the format defined
      below.
    publish:
      message:
        $ref: '#/components/messages/gsmRecord'
components:
  messages:
    gsmRecord:
      name: GsmRecord
      title: GSM Record
      summary: >-
        Represents information recorded about a GSM tower at a particular time
        and geographic location.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/gsmRecordPayload'
  schemas:
    gsmRecordPayload:
      type: object
      required:
        - version
        - messageType
        - data
      properties:
        version:
          $ref: '#/components/schemas/version'
        messageType:
          $ref: '#/components/schemas/messageType'
          description: 'The type of message, must be GsmRecord.'
          example: GsmRecord
        data:
          type: object
          description: The payload of this message that contains all the message data.
          required:
            - deviceTime
          properties:
            deviceTime:
              $ref: '#/components/schemas/deviceTime'
    version:
      type: string
      description: >-
        The version number of the Network Survey Messaging API that this message
        is based off of.
      example: 0.13.1
    messageType:
      type: string
      description: >-
        The type of this message. This value must match the message name or the
        message will not be interpreted correctly.
    deviceTime:
      type: string
      format: date-time
      description: >-
        The timestamp of when this message was created in milliseconds formatted
        as an [RFC3339
        date-time](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
        For example, `'1996-12-19T16:39:57-08:00'`.

Expected behavior

The expected behavior is

1. That the messageType value in the generated example json code block should have a value of GsmRecord.
2. That the messageType description for GSM Record should be: The type of message, must be GsmRecord.

[jonaslagoni]

@christianrowlands the problem you are experiencing here is because the standard dictates it. When you define schemas with no custom schemaFormat, it's gonna be AsyncAPI Schema Object, which is superset of JSON Schema draft 7.

Which states: https://json-schema.org/draft-07/draft-handrews-json-schema-01#rfc.section.8.3

An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. The value of the "$ref" property MUST be a URI Reference. Resolved against the current URI base, it identifies the URI of a schema to use. All other properties in a "$ref" object MUST be ignored.

Take notice of All other properties in a "$ref" object MUST be ignored.

---

I don't think there is a concept of inheritance in JSON Schema, the best they can do is use a combination of allOf, but that's not really what you want either, it's more a hack. For newer JSON Schema versions I know you can have properties alongside $ref, but can't remember which one.

There might be another schemaFormat you can use that support this better 🤔

[christianrowlands]

Thank you for the information. I looked through the other schemaFormats and I don't think they will fit my full use case.

The strange part is that the override I am describing has worked as expected since ~2020 until the beginning of 2023, and then all of a sudden broke. I am guessing that I was benefiting from some semantic behavior that was a "bug", and it was fixed recently. This is a shame because it allowed for the DRY principle when creating your AsyncAPI files.

I think I will just copy and paste a duplicate version of each item I want to "override". That seems like the safest option at this point.

I appreciate all the help with this.

[derberg]

seems to be completed discussion

@christianrowlands feel free to open a separate issue if you have further questions