Field descriptions ignored and overwritten by referenced objects

[PassKit]

Take the case of the swagger below where descriptions have been added to give context to multi-purpose objects such as Date.

    "boardingIdentityDetails": {
      "type": "object",
      "properties": {
        "identityDocument": {
          "$ref": "#/definitions/boardingIdentityDocument"
        },
        "issuingCountry": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the country of the travel document issuing authority."
        },
        "nationality": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the traveler's nationality."
        },
        "documentNumber": {
          "type": "string",
          "description": "The number or other unique identifying reference of the traveler's document."
        },
        "dateOfBirth": {
          "$ref": "#/definitions/ioDate",
          "description": "The date of birth as marked on the traveler's identity document."
        },
        "gender": {
          "$ref": "#/definitions/ioGender",
          "description": "The gender as marked on the traveler's identity document."
        },
        "issuedDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The issue date of the traveler's identity document."
        },
        "expiryDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The expiry date of the traveler's identity document."
        }
      },
      "description": "Details of document used to identify the traveler's identity."
    }

When rendered, these descriptions (and also titles) are ignored and referenced object's descriptions are used instead.

Should there not be a hierarchy, making it possible to override a referenced object's title and description?

[m-mohr]

The openAPI spec doesn't allow that. $refs get replaced and with it all the other elements on the same level. That's not a ReDoc issue.

[Tecktron]

The suggested way to handle the above case, reusable definitions from a $ref with different descriptions, is to use the following structure (which is valid JSON schema):

"myObject": {
    "allOf": [{ "$ref": "#/definitions/path" }],
    "description": "Here the description where I expected to set it"
}

However the issue I've found with ReDoc, is that the $ref in the allOf does not get pulled into the definition correctly. But that issue can be found in this ticket: https://github.com/Redocly/redoc/issues/915