v3.2: ambiguity/error with documentation of contentType in the encoding object

[karenetheridge]

The documentation for the "encoding" object describes contentType as a comma-separated list of media-types (wildcards permitted).

• what is the purpose of listing more than one media-type here? When deserializing a message body, how do we know which one to use? And when serializing, what purpose does this field serve?
• this is inconsistent with the schema, which specifies that the property is format: media-range, which a comma-separated list is not.

The example which uses this, https://spec.openapis.org/oas/latest#example-url-encoded-form-with-binary-values, also does not clarify how the contentType of "image/png, image/jpeg" is to be used.

[handrews]

what is the purpose of listing more than one media-type here?

It's essentially an anyOf, and the contentType: image/png, image/jpeg example is analogous to this sort of construct, and handled similarly:

requestBody:
  content:
    image/png: {}
    image/jpeg: {}

When deserializing a message body, how do we know which one to use?

If one is more specific than another, use the more specific (this is explicit for the content fields, and the usage is intended to be analogous). If they are distinct from each other (as with image/png, image/jpeg), typically only one of them will be valid. Which is the same problem you have in the content field example above.

And when serializing, what purpose does this field serve?

It lets you validate that you got either a PNG or JPEG before bothering to serialize the message, again just as if you are serializing a content field as shown above.

this is inconsistent with the schema, which specifies that the property is format: media-range, which a comma-separated list is not.

Oof. That's a schema bug, then. This is a weird corner and probably no one noticed the mismatch. They probably just grabbed it from the object key under content, not realizing that the Encoding Object's contentType squishes the keys together into a string.