Skip to content

Path Templating Clarification: Is a variable without a corresponding path parameter valid? #1830

Closed
@tedepstein

Description

@tedepstein

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", the name 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions