In schema objects, using allOf to add a description to a $ref?

[sensibleish]

It seems a somewhat common challenge is the inability to combine $ref with other attributes. For my use case, building schema objects and leveraging reusable models, the only additional attribute I need is adding a description for how the model is being used in context. I think I have a workaround and am hoping more knowledgeable folks can give feedback.

An example resuable model is an imageAsset schema representing an item from a digital asset repository:

title: Image Asset
type: object
description: "An image and associated metadata"
properties:
  url:
    type: string
  caption:
    type: string

Its description is not useful for explaining the purpose of the image asset in the referencing schema. Let's say I have a schema for restaurant that includes an image:

title: Restaurant
type: object
properties:
  overviewImage:
    $ref: "#/components/schemas/imageAsset"

This pulls in the description from imageAsset, which is irrelevant to the context. I need to set a description to explain the meaning of overviewImage.

Putting the $ref inside an allOf seems to allow that:

openapi: 3.0.0
info:
  title: Test
  version: '1'
paths:
  /test: {}
components:
  schemas:
    imageAsset:
      type: object
      description: "An image and associated metadata"
      properties:
        url:
          type: string
        caption:
          type: string
    restaurant:
      type: object
      description: "A restaurant"
      properties:
        overviewImage:
          description: "The primary image for marketing content"
          allOf:
            - $ref: "#/components/schemas/imageAsset"

The syntax validates and the web-based Swagger Editor's preview shows the desired result. Is this a reasonable approach?

[handrews]

In terms of JSON Schema, this is the recommended approach.

The latest draft formalizes some internal mechanisms to help tooling make use of it, but if Swagger Editor already handles it correctly then that's great!

Note that OAS 3.1 is likely to adopt the latest JSON Schema draft per #1977 , which will allow putting the $ref and description together in the same object and skipping the allOf (as long as they's only one $ref anyway- if you need more than one you'll still need allOf because duplicate JSON property names have undefined behavior.

[MikeRalphson]

Closing as above, thanks @handrews

[sensibleish]

@handrews Thank you very much!