OpenAPI 3.1.1/3.0.4 support: File Upload does not support OpenAPI 3.1.1/3.0.4

[thrandale]

Q&A

• OS: Windows
• Browser: Chrome
• Version: 117.0.5938.132
• Method of installation: npm
• Swagger-UI version: 5.4.2
• Swagger/OpenAPI version: OpenAPI 3.1.0

Content & configuration

With type: binary

With contentMediaType: application/octet-stream instead

Example Swagger/OpenAPI definition:

# The Openapi 3.0 way
requestBody:
  Document:
    content:
      multipart/form-data:
        schema:
          type: object
          required:
            - File
          properties:
            File:
              type: string
              format: binary

# The OpenAPI 3.1.0 way
requestBody:
  Document:
    content:
      multipart/form-data:
        schema:
          type: object
          required:
            - File
          properties:
            File:
              type: string
              contentMediaType: application/octet-stream

Describe the bug you're encountering

This article from OpenAPI describes the conversion from OpenAPI 3.0 to 3.1.0 Migrating from OpenAPI 3.0 to 3.1.0.

For a file upload in 3.0 you would specify format: binary. in 3.1.0 you now specify contentMediaType: application/octet-stream instead. Swagger will only show the "Choose File" button if you have the format: binary specified.

Expected behavior

I should be able to specify a schema like this and get the "Choose File" button

multipart/form-data:
  schema:
    type: object
    required:
      - File
    properties:
      File:
        type: string
        contentMediaType: application/octet-stream

[aldokkani-newcross]

Can someone address this problem?

[dipakTankTR]

Can we address this issue

[rfelgent]

anybody ?

[akalongman]

Any updates?

[char0n]

Hi everybody,

As part of this issue, OpenAPI 3.1.1 and OpenAPI 3.0.4 support will be aligned with the spec.

Refs #10335

---

Execution plan

We'll introduce proper support for OpenAPI upload in 3 layers.

Layer 1

Fix the current code so that type & format combos are aligned with the spec. The combo works both in OpenAPI 3.1.x and OpenAPI 3.0.x.

format=base64 is invalid and not existing. We should assert format=byte.

---

We should compare the media-type and media-range non-terminals differently, than we currently do. The reason is that both non-terminals can contain parameters.

application/octet-stream; param=1 - valid media-type/media-range

So instead of doing:

 if(
    contentType === "application/octet-stream"
    || contentType.indexOf("image/") === 0
    || contentType.indexOf("audio/") === 0
    || contentType.indexOf("video/") === 0
    ...
  ) {

We should be doing:

 if(
    contentType.startsWith("application/octet-stream")
    || contentType.startsWith("image/")
    || contentType.startsWith("audio/") 
    || contentType.startsWith("video/") 
    ...
  ) {

---

We should access the JSON Schema type keyword depending on OpenAPI version. In OpenAPI 3.0.x type==="string" assertion is fine, but in OpenAPI 3.1.x we have to do assertion as following expression: type==="string" || (Array.isArray(type) && type.includes("string"))

Layer 2

This layer is OpenAPI 3.1.x specific and modifies getType function form json-schema-2020-12 plugin, specifically inference of the type from the contentMediaType and contentEncoding keywords. When either one of those keywords is there, we can infer type="string".

Layer 3

Handling of new contentMediaType and contentEncoding keywords in OpenAPI 3.1.x.

Rules (assuming type="string" and format: * have not been defined):

1. presence of specific contentType (key of attached Media Type Object) like "application/octet-stream", "image/", etc.. make below rules inconsequential and always indicate file input
2. contentMediaType or contentEncoding has precedence/priority over type=string && format: byte | binary combo
3. presence of contentMediaType containing any value indicates file input
4. presence of contentEncoding when contentMediaType present, is inconsequential
5. presence of contentEncoding when contentMediaType is not present indicates file input
6. presence of combo type=string && format: byte | binary is asserted as the last option

There is an ambiguous case for rule 5. contentEncoding SHOULD be associated with type="string". But if type is omitted, JSON Schema treats the schema as applying to any type (open-ended). Therefore, in spec terms: it's valid, but ambiguous — it should be assumed to apply to strings. It will be addressed (to certain level) by Layer 2.