is there a way to describe that one of a couple of headers is required?

[samzilverberg]

We wanted to describe a GET endpoint that requires oneOf two headers.
Our nodejs+fastify+ajv+json schema combo has no problem describing and validating this.
But when trying to create an openapi 3.1.x spec for this we didn't find anyway to describe this.

The request headers area (parameters) allows a schema but it is for a specific named header (field name).

for now we're just describing this requirement via the description of the endpoint.

Am I missing somehting? or is this a limitation of the current specs?
If the latter, is there any interest in changing it in the future?

[handrews]

@samzilverberg you are not missing anything. This will almost certainly be changed in 4.0 "Moonwalk". I'm not sure there's much we could do in 3.2 as adding cross-parameter relationships would be complex to do in a backwards-compatible manner.

[samzilverberg]

Thanks for the answer, was starting to question my sanity 😄 .

Re 3.2 & backwards-compatabilitiy:
I'd be happy to see a new section (next to parameters) or new discriminator field (in parameters) that would allow specifiying headers as a json schema (or somehting more limited if this is too broad).
It could be beneficial as a step in the direction you want to take in 4.0 Moonwalk (I found some discussion here)

This wouldn't have to be backwards-compat with anything existing.
A specs maintainer could choose to either use the parameters way or the "new way" to describe headers.

I'm not here to start a huge discussion about it or challange any decisions.
I trust you're already having good discussions about everything related to openapi.
That's just me leaving my 2 cents while already visiting here ;)

[handrews]

@samzilverberg I've been contemplating this sort of stuff in the context of 3.2. The primary constraint is how much work tooling vendors can and will take on and deliver 3.2 support in a short time frame. We do not want a repeat of 3.1, which the time frame is 3+ years (there were good reasons why 3.1 had to be done the way it was, but we dealt with those reasons in 3.1 and do not want to repeat the experience now that they no longer apply).

Parameters are already one of the most complex areas. Introducing a completely new parallel system would be a lot of work. But would it perhaps be less work than tweaking the existing system here or there, so that 3.1 parameter support could be left alone and a new thing built alongside it that might transfer more smoothly to Moonwalk? That's the big question. I think ultimately we'll have to talk with tooling maintainers, but it is something I'm thinking on.

One complication is that we're not really sure where Moonwalk is going. Most of the discussions there do not reflect recent efforts to better understand tooling needs and align the specification accordingly. But there is a general agreement that a more comprehensive, unified strategy towards parameters is needed.

Hopefully we'll have a 3.2 plan by the end of the year that we can socialize after the new year (given the usual slowdown in December).