Can we get clarification on how to post multipart/form-data containing an array of items of type X?

[spacether]

Can we get clarification on how to post multipart form data with an array of items of type X? Here is an example requestBody:

      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items: {}
                bools:
                  type: array
                  items:
                    type: boolean
                strings:
                  type: array
                  items:
                    type: string

1 What if x is a boolean?

2. Are the rfc accepted string serializations for booleans or should we use json?
3. What if X is multipart/octet-stream binary data, should the array be exploded? If so should the name be files or files[]?
4. If x is type string, should the array serialized with explode = True or False?
5. When should explode be true and when should it be false for multipart form data?
6. What count as primitive types aside from strings? int? float? bool? null?
7. Should empty arrays be sent with json content-type because explode would not send their data? Any actual examples including the data sent in each multipart section would be a great help.

It looks like this PR is related: https://github.com/OAI/OpenAPI-Specification/pull/2066

[spacether]

Form here in the spec:

To upload multiple files, a multipart media type MUST be used:

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items: {}

It looks like explode=True for multipart form arrays of files.

[MHamzaRajput]

explode=True is not working for multipart/form-data request

[handrews]

The style field in the Encoding Object is only valid for application/x-www-form-urlencoded, so it cannot be used with multipart media types.

I'm fairly certain that means that the cases asked about in this issue are all invalid.

[spacether]

style is defined as Describes how a specific property value will be serialized depending on its type. See [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) for details on the [style](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) property. The behavior follows the same values as query parameters, including default values. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of [contentType](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#encodingContentType) (implicit or explicit) SHALL be ignored. So isn't multipart/form-data explicitly covered by style?

Also this issue asks for clarification when style is unset. If the answer is to point to an RFC that is fine, but the RFCs that I looked at lacked these examples.

[handrews]

@spacether I see what's going on here. In OAS 3.0, style and explode apply only to application/x-www-form-urlencode, but in OAS 3.1 they apply to both application/x-www-form-urlencoded and multipart/form-data.

So if @MHamzaRajput is using OAS 3.0, that would explain why explode: true is not working for them.

Regarding your questions (in the context of OAS 3.1):

• Anything that is not an array or object is a primitive type
• I don't see anything in RFC 6570 about how to serialize or parse booleans or nulls. Given that JSON is the most common data format for APIs described with OpenAPI, I'd guess that the JSON representations are the most reasonable to use, but agree that it could be more clear
• It seems pretty clear to me that the type of X (the thing within the array or object) is irrelevant when considering explode. If I am reading this right, exploding the array just means making a part of the multipart for each element, and that's no more or less complicated for any of the options you raise, including binary application/octet-stream (it's arguably less complicated, as I have no idea what you'd do with an unexploded array of binary data - you can't stuff it in a JSON array, for example)
• I don't think the spec does or should advise on when to use explode or not, except perhaps to note things like an unexploded array of binary file data not having any clear representation. Aside from that sort of thing, the answers will differ depending on the needs of the API.
• I don't entirely understand question 7, but you should only send application/json for an empty array if you would have been sending application/json for a non-empty one. An empty array shouldn't change the nature of the data, just the amount.

[handrews]

At minimum, a bit of clarification on the expected string form of boolean and null values is probably worth including in a patch release, so I'm labeling this appropriately. Even if that clarification ends up being "do whatever works for your environment." For example, Perl does not have a boolean type, so it's not always possible to round-trip JSON-like booleans.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921! This is addressed in the new Appendix B.