v3.3: provide additional guidance on usage of "style" with multipart/form-data

[karenetheridge]

see also #5406

I'm assuming this change is too great to be backported to 3.2.1.

• no schema changes are needed for this pull request

[miqui]

hi @karenetheridge I went through #5406. I did several passes to get a more solid understanding. However, I am still a bit confused. Is explode to be treated as a workaround or fix? Was it simply missing from the language in the spec?

[karenetheridge]

@miqui I don't understand your question, so let me summarize what I'm seeing:

• issue OpenAPI 3.0 does not support csv-serialized form-data arrays #2018 was created because a gap in the spec was noticed in 3.0, that the equivalent of collectionFormat: csv was no longer available when serializing multipart/form-data messages
• PR Support style, explode, allowReserved encoding for multipart/form-data #2066 was created to resolve this issue, by adding "or multipart/form-data" to the section of the spec that says "This field SHALL be ignored if the request body media type is not application/x-www-form-urlencoded" (ref. https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-for-rfc6570-style-serialization); by doing so, it was then possible to use type: array or type: object with style: form and explode: false to create CSV values in multipart requests.
• however, no additional guidance was added about how the other style and explode combinations would work. Notably, arrays and objects with explode: true cannot be serialized or deserialized given the way the encoding object is constructed right now (encoding objects apply to multipart parts, not the message as a whole).

Therefore, I propose that we explicitly mention these non-functional combinations, and in a version of the spec that allows breaking backwards compatibility we prohibit them outright.

[karenetheridge]

rebased, and suggested change accepted.

[handrews]

@miqui you'll need to re-approve this b/c of the latest linter fixes.

[karenetheridge]

side note - I'm assuming this change is too great to be backported to 3.2.1.

[miqui]

@karenetheridge > side note - I'm assuming this change is too great to be backported to 3.2.1.

I tend to agree with you. Interested to see what others feel.