$ref siblings

[mikeharder]

The behavior of $ref sibling propeties varies across different spec versions:

Allowed - All Properties

• OpenAPI 3.1 (https://spec.openapis.org/oas/v3.1.0#schema-object)
• JSON Schema 2020-12 (https://json-schema.org/draft/2020-12/json-schema-core#section-8.2.3.1)

Allowed - Selected Properties

• MS Swagger (https://azure.github.io/autorest/openapi/howto/$ref-siblings.html)

Ignored

• OpenAPI 2.0 (https://swagger.io/docs/specification/using-ref/)
• OpenAPI 3.0 (https://swagger.io/docs/specification/using-ref/)
• JSON Schema Draft 5 (https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-7)

Mixing specifications from one bucket, with tools from another bucket, may be problematic.

For example, given this spec:

schemas:
  Foo:
    myProp:
      $ref: "#/components/schemas/Bar"
      readonly: true

The readonly property may be ignored or included, depending on the spec version.