$ref siblings - Githubissues

Azure / azure-openapi-validator

Azure Open API Validator

MIT License

47 stars 46 forks source link

$ref siblings #705

Closed mikeharder closed 5 months ago

mikeharder commented 5 months ago

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.