v3.2: use of cookies with style=form or style=cookie, explode=false with arrays and objects is invalid and should be immediately deprecated

[karenetheridge]

https://spec.openapis.org/oas/latest#style-examples describes the cookie style as:

• explode=false, array: color=blue,black,brown
• explode=false, object: color=R,100,G,200,B,150

That is, just like style=form; the only difference is that in the query string the serialized parameters are concatenated with &, and in the Cookie header the serialized parameters are concatenated with ; .

However, RFC6265 clearly sets out the syntax restrictions for cookie-pairs: the comma character (,) is prohibited (ref: https://www.rfc-editor.org/rfc/rfc6265#section-4.2.1 and https://www.rfc-editor.org/rfc/rfc6265#section-4.1.1.):

 cookie-pair       = cookie-name "=" cookie-value
 cookie-name       = token
 cookie-value      = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
 cookie-octet      = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
                       ; US-ASCII characters excluding CTLs,
                       ; whitespace DQUOTE, comma, semicolon,
                       ; and backslash

Use of this prohibited character in a Cookie header string could lead to surprising results at any point in the network stack, in a client or a server, since this character is not permitted. Therefore its use must NOT be condoned.

I believe this means that we must:

• immediately deprecate this style/explode/type combination (in:cookie, style:form or style:cookie, explode:false for arrays and objects) in the next point revision of the specification and explain why its use is highly discouraged;
• and remove it entirely (indicate this combination is prohibited) in the next major release of the specification (4.0).

Luckily the default value for explode in both style: form and style: cookie is true, so the OAD author would have to explicitly mark a parameter as using explode: false. This also makes it easier to prohibit these combination of configs in the OAD schema itself.

(Technically the use of this config combination is okay for arrays when there is only one value in the array, or zero keys in the object, as the comma delimiter won't appear, but the serialization here is identical with explode=true, so allowing this edge case adds no utility and would only cause confusion.)

Note this issue applies to all previous versions of the specification as well (3.0.x and 3.1.x), as the issue is the same when using style=form for cookie parameters. We should probably do point release fixes for these as well.

[handrews]

Good catch.

[karenetheridge]

Appendix D "Serializing Headers and Cookies" is probably the only section that needs editing, other than removing the invalid examples for arrays and objects with style=cookie and explode=false -- style=form with explode=true is still okay for objects, as & and = are legal in the Cookie header, but we really need to steer users towards the cookie style (and this is a great reason for tooling to support 3.2).

Also, the example with serializedValue: "greeting=Hello%2C world!; code=42" needs to be fixed.