Why "all other properties in a "$ref" object are ignored"?

[geoff-maddock]

I was curious about why this is the case - I'm building an API from the ground up using Open API 3.0, and in some of my schemas I'm using compositional references to build the schemas, for example:

        UserId:
            description: The unique identifier of a user
            type: integer
            example: 751

        Quote:
            type: object
            properties:
                id:
                    $ref: "#/components/schemas/QuoteId"
                    example: 1000
                company:
                    type: string
                    description: Company name at the time of the quote
                    example: Dunder Mifflin
                    maxLength: 140
                prepared_by:
                    $ref: "#/components/schemas/UserId"
                    example: 751
                    description: ID of the user who created the quote
                approved_by:
                    $ref: "#/components/schemas/UserId"
                    example: 751
                    description: ID of the user who approved the quote

However, when editting using https://editor-next.swagger.io/, I'm getting errors on the lines such as prepared_by and approved_by, stating All other properties in a "$ref" object are ignored. In this case, it would seem to me that these fields would or could have different descriptions than the schema they are referring to, because they represent something else.

Is there any other way of doing this, or does someone have an explanation as to why this is a feature of the spec?

[MaceWindu]

Check 4.7.24 Reference Object

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

1. Taking into account spec, https://editor-next.swagger.io/ should actually complain about id too as it contains prohibited example property
2. OpenAPI 3.1.0 relaxes it a bit allowing summary and description properties, which still doesn't allow example

When I use different open-api documents from internet to test my parser I often see this rule broken. If you want to extend your schema, you shold use allOf:

• https://spec.openapis.org/oas/v3.1.0#composition-and-inheritance-polymorphism
• https://json-schema.org/understanding-json-schema/reference/combining.html?highlight=allof#allof

[handrews]

OAS 3.0 inherited this behavior from the old (and long since expired) JSON Reference proposal.

See #3526 (comment) for an explanation of why (for now) only summary and description are allowed in 3.1.

[handrews]

Since this was initially answered in 2022 with no further discussions, I'm going to close it as answered.