description tag not read if $ref tag exists

[maybeec]

The following snippet declares a property to be an object of a specified reference. However, the description of the property is not read such that the parser always returns null on the propertySchema.getDescription()

components:
  schemas:
    SampleData:
      x-component: comp
      type: object
      properties:
        mainData:
          type: object
          description: a single ref to MoreData (one-to-one)
          $ref: '#/components/schemas/MoreData'

This is different to the case, where you declare an array type of references like

components:
  schemas:
    SampleData:
      x-component: comp
      type: object
      properties:
        mainData:
          type: array
          description: a single ref to MoreData (many-to-one)
          items:
            $ref: '#/components/schemas/MoreData'

In this case, the description is correctly gathered by the parser.

[tedepstein]

@maybeec , this is actually a restriction that comes directly from the JSON Reference specification:

3. Syntax

   A JSON Reference is a JSON object, which contains a member named "$ref", which has a JSON string value. Example:

   { "$ref": "http://example.com/example.json#/foo/bar" }

   If a JSON value does not have these characteristics, then it SHOULD NOT be interpreted as a JSON Reference.

   The "$ref" string value contains a URI [RFC3986], which identifies the location of the JSON value being referenced. It is an error condition if the string value does not conform to URI syntax rules. Any members other than "$ref" in a JSON Reference object SHALL be ignored.

[maybeec]

Thanks to make this clear. Did not know about it. It is a little strange in this specific part here, but obviously the parser is than behaving correctly.

[andylowry]

@maybeec It definitely is strange in my opinion, and creates a restriction with no value that I can deduce. Yet there it is.

It's interesting to note that Swagger and OAS3 actually violate this in their definition of how a "Path Item" works. Unlike anywhere else in the specification, they list $ref as a property of a path item, and the description implies that the intention is to "mix" the external path item's properties in with the local object - much as you want to do with your schema reference.

The KaiZen parser does not currently implement this, and I don't view it as a high priority.

[maybeec]

@andylowry totally agree and I appreciate that you keep your code clean and compliant to the specification!