What properties can / should be siblings to $ref?

ref-siblings.md

From

https://github.com/Mermade/openapi-specification-extensions/blob/master/refs/combined.csv

we can see that the vast majority of uses (at the time the survey was run) are for description on it's own, description with some x-extension or for schema-related keywords - this latter case is no longer a concern as we delegate the behaviour of $ref in schemaObjects to JSON Schema rules.

What are the candidates for $ref siblings?

Peer Objects

• Response
• Parameter
• Example
• RequestBody
• Header
• SecurityScheme
• Link
• Callback

Plus in v3.1.0

• Webhook

Properties of Peer Objects

Note: does not include patternProperties, additionalProperties etc

• Response properties/description
• Response properties/headers
• Response properties/content
• Response properties/links
• Parameter properties/name
• Parameter properties/in
• Parameter properties/description
• Parameter properties/required
• Parameter properties/deprecated
• Parameter properties/allowEmptyValue
• Parameter properties/style
• Parameter properties/explode
• Parameter properties/allowReserved
• Parameter properties/content
• Parameter properties/examples
• Example properties/summary
• Example properties/description
• Example properties/externalValue
• RequestBody properties/description
• RequestBody properties/content
• RequestBody properties/required
• Header properties/description
• Header properties/required
• Header properties/deprecated
• Header properties/allowEmptyValue
• Header properties/style
• Header properties/explode
• Header properties/allowReserved
• Header properties/content
• Header properties/examples
• Link properties/operationId
• Link properties/operationRef
• Link properties/parameters
• Link properties/description
• Link properties/server

Possible actions

• Declare any OAS field called description is an annotation for the purposes of $ref resolution, and specify that OAS as the application has the behaviour that annotations override those in the $refed object.
• Extend this to all specification extension properties.
• Extend to include summary, required, deprecated ?
• @darrelmiller mentioned examples

RC0
Summary and Description are a GO!!!!! They override equivalent in $ref'd object.

RCn?
Required and deprecated are a maybe, maybe not.
examples - Henry says yes. Mike(R|K) are for! Ron is a maybe.
x- ????