I'm breaking this out from discussion #5314 which covers allowing various fields at multiple levels.
This issue is to consider the implementation challenges of a global (OpenAPI Object in the entry document) parameters field.
TL;DR:
in: path — keep the existing mandatory required: true and make it an error any time an in: path parameter does not match a path template variable; this limits the utility of global in: path parameters, but that's finein: querystring — this can only be used once per operation, so setting it globally is unlikely to be useful, but we needn't forbid it; this is probably rarely used even at the Path Item level for the same reasonin: header — it's already possible to specify headers at the Path Item level that don't make sense for every operation, so it doesn't matter if it's also possible at the global level; we don't worry about it now, and we don't need to start worrying about it
I can't think of any concerns with in: query or in: cookie parameters that don't already exist with the Path Item plus Operation levels.
More details and options below for those interested:
global in: path parameters
Use case: Every item path template looks like /foo/{id}, so there is a desire to specify the id path parameter globally.
Problem: Not every path template is an item template, and in: path parameters MUST state required: true
- If other path templates have an
id path parameter with different syntax or semantics, then defining one globally is just a user error, and we need not concern ourselves with it.
- If (as is likely), some path templates don't have an
id path parameter at all, what happens?
- If it is an error (retaining the
required: true requirement), we are making a useful use case impossible.
- If we allow
required: false on path parameters, we could say that that means that it can be ignored if there is no matching path template variable; however this behavior is more complex and no longer just adding another level
My thought is that for 3.3, we retain required: true, so ending up with an in: path parameter that does not match a path template variable is always an error. This is the simplest option, and we can add more functionality in a future release if there is strong enough demand.
global in: querystring parameters
Since you can't have two of these on the same operation, regardless of where they were defined, nor can you combine them with any in: query parameters, this will probably not be used globally. And probably isn't often used at the Path Item level.
This restriction mostly exists to keep request matching complexity to a manageable level. Note that there is a weird exception in that an API Key query parameter presumably gets tacked on regardless, as we don't address it. We should probably clarify that.
My thought for 3.3 is to not do anything special about this. No one has complained about it AFAIK, so let's keep going. API Keys are a SAF and by definition cause exceptions to normal rules, so it being an exception already is fine.
global in: header parameters
Similarly, some request headers are broadly but not universally useful. However, unlike path template variables, there is no required: true requirement.
Specifying an irrelevant header parameter is possible now, and we don't worry about it. For example:
/foos:
parameters:
- in: header
name: Prefer
schema:
type: string
pattern: ^return=(minimal|representation)
get: {...}
post: {...}Applying this preference to the GET request doesn't really make sense, as GET by definition returns the representation. A return=minimal GET request would effectively be a HEAD request.
And for that matter, as written above, the Prefer header parameter would apply to a HEAD operation (even though none is explicitly described), which also doesn't make any sense.
My thought for 3.3 is that we don't worry about this now, and I suggest we continue to not worry about it. It might not make sense, but irrelevant HTTP fields are generally silently ignored, so even if someone sent this field (and note that it is not required), it is unlikely it would cause a problem.
I'm breaking this out from discussion #5314 which covers allowing various fields at multiple levels.
This issue is to consider the implementation challenges of a global (OpenAPI Object in the entry document)
parametersfield.TL;DR:
in: path— keep the existing mandatoryrequired: trueand make it an error any time anin: pathparameter does not match a path template variable; this limits the utility of globalin: pathparameters, but that's finein: querystring— this can only be used once per operation, so setting it globally is unlikely to be useful, but we needn't forbid it; this is probably rarely used even at the Path Item level for the same reasonin: header— it's already possible to specify headers at the Path Item level that don't make sense for every operation, so it doesn't matter if it's also possible at the global level; we don't worry about it now, and we don't need to start worrying about itI can't think of any concerns with
in: queryorin: cookieparameters that don't already exist with the Path Item plus Operation levels.More details and options below for those interested:
global
in: pathparametersUse case: Every item path template looks like
/foo/{id}, so there is a desire to specify theidpath parameter globally.Problem: Not every path template is an item template, and
in: pathparameters MUST staterequired: trueidpath parameter with different syntax or semantics, then defining one globally is just a user error, and we need not concern ourselves with it.idpath parameter at all, what happens?required: truerequirement), we are making a useful use case impossible.required: falseon path parameters, we could say that that means that it can be ignored if there is no matching path template variable; however this behavior is more complex and no longer just adding another levelMy thought is that for 3.3, we retain
required: true, so ending up with anin: pathparameter that does not match a path template variable is always an error. This is the simplest option, and we can add more functionality in a future release if there is strong enough demand.global
in: querystringparametersSince you can't have two of these on the same operation, regardless of where they were defined, nor can you combine them with any
in: queryparameters, this will probably not be used globally. And probably isn't often used at the Path Item level.This restriction mostly exists to keep request matching complexity to a manageable level. Note that there is a weird exception in that an API Key query parameter presumably gets tacked on regardless, as we don't address it. We should probably clarify that.
My thought for 3.3 is to not do anything special about this. No one has complained about it AFAIK, so let's keep going. API Keys are a SAF and by definition cause exceptions to normal rules, so it being an exception already is fine.
global
in: headerparametersSimilarly, some request headers are broadly but not universally useful. However, unlike path template variables, there is no
required: truerequirement.Specifying an irrelevant header parameter is possible now, and we don't worry about it. For example:
Applying this preference to the GET request doesn't really make sense, as GET by definition returns the representation. A
return=minimalGET request would effectively be a HEAD request.And for that matter, as written above, the
Preferheader parameter would apply to a HEAD operation (even though none is explicitly described), which also doesn't make any sense.My thought for 3.3 is that we don't worry about this now, and I suggest we continue to not worry about it. It might not make sense, but irrelevant HTTP fields are generally silently ignored, so even if someone sent this field (and note that it is not required), it is unlikely it would cause a problem.