fix: fix type for Header.schema fixed field

[char0n]

Affected section: https://spec.openapis.org/oas/v3.1.1.html#fixed-fields-for-use-with-schema-0

Schema Object | Reference Object would create ambiguity as both objects can only have $ref field. When Schema Object is a type for a field, it shouldn't use union with Reference Object as the Schema Object is already reference-able by itself.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

Huh. We fixed this in 3.2 and must have missed it in 3.1.

[amritk]

Thats funny I ran into this same issue last week!

[handrews]

@amritk This is just a bug, so definitely treat it as Schema Object-only in any implementation. Anything in 3.1 where either the Schema Object or the Path Item Object is said to have a Reference Alternative is an error, as both of those Objects already have their own $ref fields which behave differently from the Reference Object (and from each other).

[amritk]

@handrews does this mean any object can have a $ref now as it would be part of json schema?

[handrews]

@amritk no I just mean that in OAS 3.1 (and later), the Schema Object includes JSON Schema's $ref keyword, so an Object with just a $ref that appears where a Schema Object is expected is still a Schema Object, with JSON Schema draft 2020-12's $ref behavior. In OAS 3.0, the Schema Object did not include JSON Schema's $ref, so a $ref where a Schema Object was expected was actually a Reference Object- which was written the way the line being changed here is written, as we just missed this when updating such lines for 3.1. And 3.1.1, apparently.

The thing with the Path Item Object dates back to 2.0 and is a different kind of weird. It also defines its own $ref keyword, with rather vague behavior regarding adjacent fields.

Everything else needs to allow a Reference Object in order to use $ref.

[amritk]

Got you! Thanks for the clarification! We'll make those changes later this week