Feature Request: Allow sibling elements with $ref that overrides the references definition

[juzerali]

Currently I can either specify a $ref or the complete property description. However there are use cases where refenced definition needs to be overridden, particularly description.

components:
    schemas:
        Money:
            description: Represents monetary value
            properties:
                currency:
                    type: string
                amount:
                    type: integer

properties:
    minimum_amount_value:
        $ref: '#/components/schemas/Money'
        description: Minimum amount required to make a transaction

In the above example, I can't both reuse Money model and explain it's property semantics. It shouldn't be this way. I believe all the properties in $ref should be overridable, but at the very least description should be.

[hkosova]

$ref siblings as in your 2nd example are already supported in OpenAPI 3.1 / JSON Schema 2020-12.

Schema $refs support any sibling keywords. Outside of schemas (e.g. in parameters or responses), $refs only support sibling summary and description.

[jdesrosiers]

It's important to note that although JSON Schema 2020-12 allows $ref to have siblings, the sibling keywords do not override the keywords in the referenced schema, they add to them. In the given example, both values for description apply the /properties/minimum_amount_value schema.

However, for meta-data keywords, such as description, that don't effect validation, the spec allows for implementations to choose one or the other. So, in the given example, the second description might override the first, but it depends on the implementation.

https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.7.7.1.1

[MikeRalphson]

Please chase if the above didn't answer your question (I see the OP's thumbs up).