$ref handling incorrect when alongside other json schema attributes for OpenAPI 3.1 Spec

[TristanSpeakEasy]

Here is an example of a schema that I believe isn't handled correctly:

schema:
  title: destination-amazon-sqs
  $ref: '#/components/schemas/destination-amazon-sqs'

For OpenAPI 3.0 this is being handle such that it is just treated as a reference which I believe is correct.

But for 3.1 which is using JSON Schema Specification Draft 2020-12 this

"allows keywords alongside $ref as a shorthand to putting two schemas inside an allOf"

which is a quote from a comment in this stack overflow question https://stackoverflow.com/questions/56749522/using-a-ref-and-other-properties-within-a-json-schema and while it is not explicitly called out here https://json-schema.org/understanding-json-schema/structuring.html#ref it does list the 3.0 behaviour versus 3.1

In Draft 4-7, $ref behaves a little differently. When an object contains a $ref property, the object is considered a reference, not a schema. Therefore, any other properties you put in that object will not be treated as JSON Schema keywords and will be ignored by the validator. $ref can only be used where a schema is expected.

So my thoughts are that this should potentially return a allOf array with the two schemas split out. Thoughts?

[daveshanley]

Interesting. There are two ways to handle this: add support by crafting a new allOf entry based on what is supplied. Alternatively, the library could ignore it and include an indexing error, acknowledging the design but recommending removing the short-hand and explicitly using allOf instead.

Choice A: Support the shorthand for 3.1+ docs
Choice B: Keep existing behavior, but include an indexing error, warning of the ignored shorthand.

What would folks like to see?

[TristanSpeakEasy]

I vote choice A as we have seen OpenAPI docs use this in the wild and it is valid according to specification and it would be great to have libopenapi match the specification where possible

[daveshanley]

I think choice A is the best one. Let's do that, adding it to the backlog.

[TristanSpeakEasy]

@daveshanley just wanted to ask if you had thought anymore about if you might support this?

We are coming across more and more specifications using OpenAPI this way especially with examples, descriptions etc etc:

customer:
  type: object
  properties:
    name:
      type: string
      example: "John Doe"
    age:
      type: integer
      example: 30
    occupation:
      type: string
      example: "Engineer"
    address:
      $ref: "#/components/schemas/address"
      example: {"addressLine1": "123 Example Road", ...}

would love to see this prioritised and figure out how libopenapi can support this

[daveshanley]

I've seen a few more requests come in for this. Will support it yes - it's just a case of time to add the feature.