Style serialization/deserialization with multipart/form-data is not described well

[karenetheridge]

In Appendix C:

When using style and similar keywords to produce a multipart/form-data body, the query string names are placed in the name parameter of the Content-Disposition part header, and the values are placed in the corresponding part body; the ?, =, and & characters are not used, and URI percent encoding is not applied, regardless of the value of allowReserved.

Okay, so that would seem to suggest that a simple object e.g. { "a": 1, "b": 2 } should be serialized to this multipart body (where the message's Content-Type is multipart/form-data; boundary="4aKOX"):

--4aKOX
Content-Disposition: form-data; name="a"

1
--4aKOX
Content-Disposition: form-data; name="b"

2
--4aKOX

How is that to be expressed in the OAD? We cannot say "use style=form for the entire object", because encoding describes individual properties, not an object as a whole:

content:
  multipart/form-data:
    schema:
      type: object
    encoding:
      ???             # we need to put a property name here
        style: form   # ..but then the style would apply to individual string values, not the object

And what is the point of using style here at all, if & and = can't be used to combine multiple values, and percent encoding isn't done? A part's string value will always just deserialize to itself using form style; it's an identity function, so I don't see how it could ever be useful to include it.

---

Similarly, how would style=deepObject work here? If I have this multipart body:

--4aKOX
Content-Disposition: form-data; name="a[x]"

1
--4aKOX
Content-Disposition: form-data; name="b[y]"

2
--4aKOX

..how does that deserialize? I've just created two separate objects: {"x": 1} and {"y": 2}. Now what?

I think the spec wording quoted above is trying to say that all parts must be considered together and parsed as an array or object, but then there is nowhere to put the encoding information for that structure.

Some understanding of how style came to be used here would be helpful, because I don't see how any of this makes sense at all. I see that the addition of style for multipart/form-data was introduced for 3.1 (3.0.4 restricts style to just application/x-www-form-urlencoded, which makes more sense, as it is a single string being composed of several values, concatenated by &, just like the URI query string).

[karenetheridge]

I did some archaeology:

• OpenAPI 3.0 does not support csv-serialized form-data arrays #2018
• Support style, explode, allowReserved encoding for multipart/form-data #2066

cc @mkistler as his name is all over these issues

[karenetheridge]

My present thinking is that explode: true simply doesn't make sense for style serializing in multipart/form-data, and should be explicitly prohibited. That means no explode: true for style: form in arrays and objects, and no style: deepObject at all.

What remains is:

• style: form, primitives: the value is copied verbatim (with UTF-8 encoding) into the message part
• style: form, explode: false, array or object: the array's items or the object's key-value pairs (with UTF-8 encoding) are concatenated with comma as the separator
• style: spaceDelimited and style: pipeDelimited, explode: false for arrays and objects: as in style: form, but using (space) or | (pipe) as the delimiter.