allow any property as sibling of $ref

[robstoll]

it's nice to see that openapi spec 3.1.0 allows that one can use description alongside of $ref. However, why the restriction to description and summary only? I would like to define maxLength and other validations for $ref which are normally not included in the reference.

I now found a fitting issue (closed though):
#1514

[handrews]

@robstoll $ref in 3.1.0 Schema Objects can have any keyword alongside of it. The description and summary restriction is for Reference Objects outside of Schema Objects.

Those Reference Objects can target many other different types of Objects, which have different types of fields that interact in different ways. For 3.1, description and summary were chosen to try out this new approach. They are present in many if not most referenceable Objects, were among the most requested overrides, and are simple to implement.

But again, there is no restriction on $ref siblings in Schema Objects. That is because JSON Schema draft 2020-12 defines the validation and annotation behaviors of adjacent keywords – they do not override keywords in the reference target.

[robstoll]

Hm... not sure I get the outside of Schema Objects. I don't see this terminology here: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#reference-object -> here it only states that additional properties shall be ignored.
I assume the following is valid according to OAS

openapi: 3.1.0
info:
    title: dummy
    version: "1.0"
paths:
components:
  schemas:
    Order:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        address:
          $ref: '#/components/schemas/Address'
          maxLength: 50
    Address:
        type: object
        properties: 
            firstName: 
                type: string

but the question is whether the additional properties (here maxLength) shall be ignored or not (e.g. by an openapi generator).
Besides, for my understanding, is the reference object of address outside the Order schema object?

[handrews]

@robstoll if you scroll down just a tiny bit further, you'll see:

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Note that this restriction on additional properties is a difference between Reference Objects and Schema Objects that contain a $ref keyword.

address is a property name in a Schema Object, so it's value is also a Schema Object. As are all objects under #/components/schemas/{name} such as #/components/schemas/Address.

[robstoll]

Alright, in this case I need to look further why the openapi generator I use doesn't support it as expected. Thanks for the explanation

[handrews]

Closing as resolved - it appears to be a tooling issue.