Support for multipart/mixed (and possibly better multipart/* support in general)

[handrews]

We occasionally see folks trying to use OAS with multipart/mixed, which does not support it. But it would not be hard to define a mapping along the lines of multipart/form-data but with more of an array model. See also discussion #2599. I think @jeremyfiel also has experience with this.

[EDIT: See also multipart/x-mixed-replace which AFAICT does not have a usable specification as WHATWG explicitly states in that section that there spec "describes processing rules for web browsers" and relegates everything else to multipart/mixed... I guess non-web-browsers aren't supposed to process it? 😒 ]

[handrews]

It's also worth noting that when uploading multiple files for a form field with multipart/form-data, RFC 7578 requires having multiple parts with the same name, which can't be modeled by the current "treat it as a JSON object" approach.

[jeremyfiel]

EDIT: guess I should have read your link.

Another multipart option missing is the ability to send multiple files in a single form field.

It should be a form-data payload with a nested multipart body with individual parts for each file. There is no way to define a nested multipart payload.

This is as far as I can get with it. But no way to define the nested body parts if I were to send multiple file types

requestBody:
  content:
    'multipart/form-data':
      schema:
       name:
         type: string
       file:
         type: string
         format: binary
      encoding:
        name:
          headers:
            content-disposition:
              schema:
                type: string
          contentType: 'application/json'
        file:
          headers:
            content-disposition:
              schema:
                type: string
          contentType: 'multipart/mixed'

[handrews]

@jeremyfiel I know that multipart/mixed and similar MIME-derived formats explicitly allow nesting.

I noticed that the most recent multipart/form-data RFC, RFC 7578, deprecates the nesting in favor of multiple parts with the same name. According to the RFC's appendix, the nested approach wasn't known to be implemented but I assume you have an implementation that does it.

[jeremyfiel]

A big missing piece from the multipart/mixed RFC is the ability to define the body parts in the same way form-data uses content-disposition header.

Because the RFC is so old, and was originally for email messaging, apparently they didn't have a need to identify the body parts and the form-data RFC didn't address the /mixed RFC when updates were made for the new header.

if we could depend on this same header, I think it would help quite a lot to define mixed bodies with OAS, with the same syntax as form-data and x-www-urlencoded bodies

[jeremyfiel]

@jeremyfiel I know that multipart/mixed and similar MIME-derived formats explicitly allow nesting.

I noticed that the most recent multipart/form-data RFC, RFC 7578, deprecates the nesting in favor of multiple parts with the same name. According to the RFC's appendix, the nested approach wasn't known to be implemented but I assume you have an implementation that does it.

I'm not entirely sure we have a nested implementation, but we do heavily use /mixed payloads because we like having JSON metadata along side a file representation.

[handrews]

So it turns out that, in theory, support for multipart/mixed was added for 3.0:

• Allow different Content Types in File type parameters #222 (comment)
• enable multiple file support? #254 (comment)
• Support for multipart/mixed Content-Type #303
• Any plans for supporting multipart/related? #520
• documented requestBody #878

The question remains, how is it supposed to work? Somewhere during the extensive GitHub archaeology involved in digging this up, I thought I found an example of someone using a name parameter to Content-Disposition with multipart/mixed.

Unfortunately, name is not defined by RFC 2183, the most recent RFC defining that header in a multipart context (there is a later RFC that only applies to it with respect to top-level HTTP message bodies). However, the set of parameters is extensible, and multipart/form-data added name.

But I'm guessing that even if you can use name as a per-part Content-Disposition header with multipart/mixed, tools, including any legacy code involving in generating or parsing such messages, is unlikely to support it. So I'm a bit baffled as to how this is supposed to work.

I still need to take another pass at reading how array instances work with the Encoding Object as their might be something there, at least if all of the parts are of the same type (which kind of goes against the whole mixed part).

🤔