Description
The specification makes it clear that each defined path parameter must correspond to a same-named variable placeholder in the path:
If
in
is"path"
, thename
field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information.
But I cannot find anything in the spec that states the converse rule:
Each variable expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item's Operations.
My guess is that this rule should apply, and that this was the intent. But I don't want to make assumptions, given the long history of the spec and the abundance of edge cases where something needs to be allowed for non-obvious reasons.
This is important for OpenAPI document validation.
- Is there ever a reason to have a variable placeholder in the path without a corresponding path parameter?
- If so, I think we should add some language to the spec clarifying that this is allowed, hopefully providing some rationale for this, and a clear description the API semantics in such cases.
- Otherwise, would we consider adding the rule as stated above to be a breaking change?
- If it's a breaking change, I'd propose adding the above rule with SHOULD instead of MUST, and leaving this issue (or a follow-up isse) open for the next major spec revision so we can change it to MUST.
- Otherwise, I'd propose adding the above rule to Path Templating or to the
/{path}
field pattern in Paths Object.