Request body with multiple identical MIME types?

[mirw]

The OpenAPI definition at the bottom describes a single POST request whose body contains 2 multipart/related sections, each with the same MIME type (application/octet-stream).

It seems to be legal according to the specification (please point out why if not!)

If a server receives this request, how does it identify which of the multipart/related sections in binary1 and which is binary2?

• Does it use ordering? (The first section is interpreted to be binary1 and the second section is interpreted to be binary2.)

• Does it use some section header information? RFC 2387, which defines multipart/related mentions the Content-ID header but doesn't specify exactly how it's used.

Please can someone clarify? ...and unless I'm misreading the OpenAPI spec, should we clarify it there too?

Thanks!

paths:
  /multiple-identical-mime-types:
    post:
      requestBody:
        required: true
        content:
          multipart/related:
            schema:
              type: object
              properties:
                binary1:
                  type: string
                  format: binary
                binary2:
                  type: string
                  format: binary
            encoding:
              binary1:
                contentType: application/octet-stream
              binary2:
                contentType: application/octet-stream
      responses:
        200:
          description: OK

#303 resulted in multipart/mixed being added, but this did not address this question.

BTW, this structure is used reasonably frequently within the 3GPP 5G specs, e.g. TS 29.518.

[jdegre]

@mirw, in the 3GPP 5G APIs, the approach is to have the first body part of the multipart/related containing an application/json body part, which includes a JSON document indicating what goes inside the different binary body parts.

This "link" is done, as you indicate, with the Content-ID of each binary body part, which is required.

[mirw]

@jdegre, thanks - makes sense! So this is just documented in human-readable docs, rather than in a machine-readable way in the OpenAPI specification?

[jdegre]

@mirw, trying to reuse your example, it would be somethign like this:

paths:
  /multiple-identical-mime-types:
    post:
      requestBody:
        required: true
        content:
          multipart/related:
            schema:
              type: object
              properties:

                # Root body part (JSON)
                jsonData:
                  type: object
                  properties:
                    binary1ContentId:
                      type: string
                    binary2ContentId:
                      type: string
                # End of root body part

                binary1:
                  type: string
                  format: binary
                binary2:
                  type: string
                  format: binary
            encoding:
              jsonData:
                contentType: application/json
              binary1:
                contentType: application/octet-stream
                headers:
                  Content-Id:
                    schema:
                      type: string
              binary2:
                contentType: application/octet-stream
                headers:
                  Content-Id:
                    schema:
                      type: string
      responses:
        200:
          description: OK

So, yes, there is an attempt to fully describe it in OpenAPI. The first body part (or the "root" of the multipart/related body, as RFC 2387 calls it) contains the JSON object, with "pointers" to the ContentId's of the other body parts.

[mirw]

Thanks! Agreed.

I was observing that there's no annotation in OpenAPI that says that the binary1ContentId field is a pointer to the binary1 Content-Id header. (I was hoping that openapi-generator might be able to resolve this pointer itself.)