Duplicated paths with matrix parameters

[nschejtman]

According to this spec Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. Setting path parameters with matrix style (which have different templated names) breaks this ambiguity. Is this still considered, even if parameters are matrix style?

[webron]

@nschejtman been a while since I dealt with such a use case. Can you elaborate please? Maybe provide an example of something you'd want to work but you think based on the spec wouldn't work?

[webron]

You are correct that theoretically, there are ways to differentiate between paths if the path parameter is declared in different ways. For example, even without matrix style, you can say that petId is a number and name is a string, which should be enough to differentiate between the two (not entirely accurate, because a number can be a string too, but let's ignore that for now).

However, at the moment, the spec still considers it a duplicate and ambiguous because deciding whether two names are identical or not based on the type is not an easy task. One may consider simple use cases like the one I mentioned above, but we have to take into account complex data types that users might use which would not be as easy to differentiate (challenging tooling and applications).

All that said, we've had discussions in the past about changing this set behavior by different mechanisms (such as a prioritization field), but no specific work has been done so far to actually introduce this change.

[nschejtman]

Makes a lot of sense for the data type case. That can be a lot more ambiguous however, having different parameters with matrix serialization will never produce ambiguities since the parameter name is included in the serialized path.

Does the Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical validation hold for every parameter serialization style, regardless if in the API implementation these are non-ambiguous?

[webron]

At the moment, it does. I don't think we ever thought about the use case of matrix parameters and it might be worth further investigation. When it comes to specifications, introducing exceptions to rules can be challenging and confusing to both the end user and the tool vendors. We have a few cases where exceptions exist and we need to be careful with adding more.

Regardless, I think this is a reasonable use case to explore when we investigate the ambiguity use case further. It might actually be better to solve the issue as a whole instead of adding exception. Another thing to keep in mind is that matrix parameters usage is not particularly common, so adding the exception for this case may not be beneficial compared to the added complexity.

[nschejtman]

Excellent. Thank you @webron for your answers!

[adriangb]

This is an interesting question @nschejtman!
I think @webron made a really good point about tooling, I suspect a lot of tooling would be incompatible with the idea since routing is in many cases handled by a different abstraction level than OpenAPI spec deserialization.

[handrews]

I'm going to move this over to the Moonwalk (OAS 4) repo as it feels related to the signatures concept, which generalizes request matching beyond just the URL path template.