Use semicolon(;) in Path Parameters

[amirmasud]

I want to write an OpenAPI 3.0 swagger API doc for some OSRM APIs. There is a coordinates path parameter which is:

String of format {longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...] .

for example: 51.3462,32.5280;51.3452,32.5280;51.3619,32.5236

how can I make this format in OpenAPI 3.0 not to be percent encoded?

to allow the usage of semicolon(;) for Query Parameters we can use allowReserved: true but it's not available in path parameters.

There is another option to use arrays and utilize serialization to use style: matrix but it helps for objects to be e.g. /point;x=20;y=30 not arrays. it makes arrays for example /users/;id=3,4,5 not /users/id=3;4;5.

Is there any solution to serialize arrays by semicolon instead of comma? or let the type be string and contains semicolon?

In location-related APIs, Latitude and Longitude pairs are used often separated by comma (lng,lat) so to separate locations we need another delimiter which can be the semicolon.

I'd appreciate if you take it into consideration.

Thanks in advance

[amirmasud]

Any update guys?

[ckeboss]

Related: https://github.com/OAI/OpenAPI-Specification/issues/1840

[wangyoucao577]

@amirmasud I saw below description at the bottom of https://swagger.io/docs/specification/serialization/. Did you try it? Does it work?
style and explode cover the most common serialization methods, but not all. For more complex scenarios (for example, a JSON-formatted object in the query string), you can use the content keyword and specify the media type that defines the serialization format. For more information, see schema vs content.

[handrews]

There was an answer suggested a few years ago and no further questions, so I'm assuming it was sufficient and closing.

[handrews]

@amirmasud I just ran across this again while researching another issue, and after consulting the ABNF in RFC 3986, I don't know why you'd need to do anything here anyway - ; and , are allowed in path segments (and queries and fragments):

   segment       = *pchar
   query         = *( pchar / "/" / "?" )
   fragment      = *( pchar / "/" / "?" )
   pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
   pct-encoded   = "%" HEXDIG HEXDIG
   unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
   sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                 / "*" / "+" / "," / ";" / "="

If your tooling is percent-encoding when RFC 3986 says it doesn't need to, that's a tooling bug.

[handrews]

Ugh... actually allowReserved is more of a mess than I thought (because of RFC 6570), see issue #3759.

[handrews]

@amirmasud OK, my apologies, this is actually a spec problem, although it took me quite some time to figure it out because the relationship between allowReserved and the more obscure parts of RFC 6570 was not immediately clear.

We should fix this in 3.2.

[handrews]

Digging more deeply into this, I am wondering if you can use the content keyword, which does not use style (the part of parameter serialization that relies on RFC6570). You would have to just use text/plain and document the structure of the string (unless there's a media type governing that format, although even then there wouldn't be tooling support for mapping that media type to JSON Schema).

But you pretty much have to just document the string format on your own anyway, since (as you noted) style: matrix does not do quite what you want. @amirmasud if you're still paying attention to this issue all of these years later, would that work as a workaround? I still think we should fix this gap in 3.2, though.

[handrews]

The tricky thing here is that allowReserved was forbidden for in: path parameters to ensure that no one used it to stuff a / character in the path (additional path segments) due to the complexity that introduces for matching incoming requests. Options would seem to include:

• allow allowReserved: true including allowing / to pass through, and state what the request matching behavior is for variable path segments, even if we make it "implementation-defined" (e.g. we don't guarantee any particular behavior, so use at your own risk)
• allow allowReserved: true but forbid passing / through and require tools to report any such attempt as an error
• something else?