[oas3] Default 'explode' for cookie parameters?

According to the spec, “When style is form, the default value [for explode] is true. For all other styles, the default value is false.” However, according to this documentation, in the “Cookie Parameters” section, there are "*"s indicating the default serialization, and it is style: form, explode: false.

So which is it? Do cookies use explode by default or not?

[jwalton]

Yeah, by “a form encoded string”, I really meant “a RFC 6570 form-style query expansion”. 😃

Although, now that I go back an read RFC 6570, in order to be complaint the correct example would actually be:

Cookie id=?id=5

Because the cookie-value needs to start with a “?” to meet RFC 6570.

[jwalton]

If we’re using the encoding as described on swagger.io, then yes, and explode is true, the parameter name disappears and it becomes:

Cookie: x=7&y=hello

I mean, first when I run this through a cookie parser I get {x: '7&y=hello'}, and there’s no parser in the world that’s going to make sense of that. 😛

But I think, by the letter of the spec, this is wrong. The spec doesn’t say the cookie header is encoded as form data. The spec says if the parameter location is “cookie”, this is “used to pass a specific cookie value to the API”. So if I have:

parameter:
  in: cookie
  name: 'myParam'
  style: 'form'
  explode: true
  schema:
    type: object

So to encode this, I take my object {x:7, y: 'hello'}, I form encode it to get x=7&y=hello, then I put this in the value of cookie named “myParam”, and I get a cookie header:

Cookie: myParam=x=7&y=hello

Similarly, for:

parameter:
  in: cookie
  name: 'myParam'
  style: 'form'
  schema:
    type: number

I encode my parameter using form to get “myParam=7”, then I put this in a cookie named “myParam”, and I get:

Cookie: myParam=myParam=7

So maybe the best thing to do here is to release an OAS 3.1.0 which adds “simple” to the list of allowed cookie styles, update the docs on swagger.io to show the above as the “form” encoding for cookies (because that’s literally what the spec says) and then add some “simple” examples, too.

This leaves the default for cookies as {style: 'form', explode: 'true'}, which is a bit weird because probably no one wants that, but it works.