3.2: removes the OAS reference object from headers schema definition

[baywet]

I noticed the reference option was missing for the schema/item schema of parameter and media type, this PR addresses the oversight and will probably need to be back-ported to 3.1

EDIT: thanks to @karenetheridge input, I opted for the better alternative, to remove the OAS reference object from headers schema since that can rely on JSON schema ref instead.

[baywet]

The alternative I've considered would be to remove reference object from the headers schema fixed fields, so it relies on the JSON schema reference mechanisms. This would be a better alternative IMHO but I wanted to get feedback first. Happy to update the PR.

[karenetheridge]

I don't think this is correct. The definition for "schema" already includes $ref, and it's the JSON Schema $ref that we want here, not the OpenAPI variant. That's why we don't have a definition called "schema-or-reference" in the OAD schema.

(edited to add, after your second comment:)

Consistency is good, so I agree with your other option that we remove the -or-reference bits from the other definitions that have them.

[baywet]

@ralfhandl I think I have enough approvals for merge, but I don't have the merge permission.
Would you be so kind to merge it please?

Also do you want me to put together a PR to target 3.1 ?

[lornajane]

Sorry, this one has a conflict now, could you take another look @baywet ?

[baywet]

merged the conflicts @lornajane! This should be good to review again/merge.

[baywet]

Also, I won't be opening a PR to 3.1 as it seems this has already been fixed.

[ralfhandl]

This is now blocked by a missing test case for a schema feature added by

• v3.2: Allow allowReserved in the Header Object (left out of PR #4593 by mistake) #4680

This will be fixed by

• 3.2 test case for allowReserved in Header Object #4699