Query String in Paths

[EmDee]

The spec doesn't seem to define, if query strings are allowed in paths or not.

According to the docs on swagger.io (section Query String in Paths) this is not allowed.

There are some related issues that doesn't seem to have a definitive answer either, e.g. #123.

Are there official specs regarding this problem?

[darrelmiller]

The phase path is based on the RFC3986 definition. Therefore, paths can't contain query parameters.

[EmDee]

Is this something that should be made more explicit in the specification?

When reading the specification regarding the paths object it states Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. which would be the case for paths which only differentiate in their query params, however, the next sentence states In case of ambiguous matching, it's up to the tooling to decide which one to use. which seems to nullify the previous sentence or am I misunderstanding this?

[SteveNay-vz]

I think you're overlooking the distinction between paths and query strings, which is pretty explicit in RFC3986. The path stops where the query string starts; even if a request contains query strings, they are not considered part of the path. The description of the paths object in the specification is about paths only; it should not be understood to apply to query strings at all.

Your statement about "paths which only differentiate in their query params," confuses the two concepts. Two paths which only differentiate in their query params would be one and the same path, not two different paths.

[MikeRalphson]

which would be the case for paths which only differentiate in their query params

In

Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.

The key word is templated. The guidance refers to paths such as /users/{name} and /users/{id}.

Closing, as the spec currently as written conveys the intent.