Path Templating: Can a segment contain template variables AND static text?

[tedepstein]

The usual examples of path templating show each segment being comprised of a static text string OR a single variable expression:

/customers/{customerID}/orders/{orderID}/status

Can we have segments that contain both, in any combination? Are these legal OpenAPI 3.0 paths?

1. One static string + one template variable in a single segment:
   /customer{customerID}/orders{orderID}/status
   
   
2. Multiple strings and template variables in a single segment:
   /customer{customerID}-order{orderID}/status
   
   
3. Multiple template variables in a single segment, without static text:
   /{customerID}{orderID}/status

The only mention of "segment" in the OpenAPI spec is here:

If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object.

This kind of implies that the curly brace-delimited template variable is expected to comprise a segment. But I'm not sure that was intended. And there's no explicit statement in the spec saying that hybrid segments, or multi-variable segments, are allowed or disallowed.

If these cases are not explicitly disallowed, I would guess that someone, somewhere, is using them; and that disallowing them would be a breaking change.

Can anyone clarify the intent and the current state?

[MikeRalphson]

I can't speak to the original intent, but examples like those above are certainly in use in the wild and from the OpenAPI 2.0 era onwards. So yes, tightening this would be a breaking change. I'm not sure that I even get your "kind of" implication from the line of the spec you quote.

[tedepstein]

@MikeRalphson , thanks. This answers my question.

The kind-of-implication came from the use of the word "segment" as a stand-in for "variable expression," thus seeming to equate the two. Instead of saying:

"each path parameter MUST correspond to the associated variable expression from the path field,"

it says (in effect):

"each path parameter MUST correspond to the associated path segment from the path field."

I know it means variable expression, but it says path segment, kind-of-implying that variable expression == a single path segment.

My PR #1831, already in the pipeline, should address this ambiguity. I don't think any further clarification is needed to assert that hybrid or multi-variable segments are allowed, though it wouldn't hurt to have these in the embedded examples.

[tedepstein]

Closing. Ths is fixed in #1830.