Encoding Object contentType field: "comma-separated list of the two types"?

[handrews]

Docs for the contentType field of the Encoding Object in 3.1.0 read (emphasis added):

The Content-Type for encoding a specific property. Default value depends on the property type: for object - application/json; for array – the default is defined based on the inner type; for all other cases the default is application/octet-stream. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types

In 3.0.3 it reads (emphasis added again):

The Content-Type for encoding a specific property. Default value depends on the property type: for string with format being binary – application/octet-stream; for other primitive types – text/plain; for object - application/json; for array – the default is defined based on the inner type. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types.

Two types? Just exactly two? Was this meant to be "two or more types"? The 3.0.3. wording of "the two types" feels a bit different but no more clear to me.

[karenetheridge]

Side note: when I was looking at this area of the spec a few weeks ago while adding some multipart support in my implementation, I noticed that the schema specifies this field as a "media-range" format, which isn't a standard format. If one happened to use a custom jsonSchemaDialect that used the format-assertion vocabulary, validation would fail (as use of that vocabulary means that usage of unsupported formats will fail validation).

Also, "inner type" in that paragraph needs clarifications. An example would help too :)

[handrews]

"inner type" means whatever type is in the items schema for the array, IIRC. I agree it should be more clear, and I'll try to address that in a PR somewhere. I'll leave the examples to someone else - no one ever likes the stuff I come up with for examples 😅

[handrews]

@OAI/tsc review request: Does anyone know what this was supposed to mean?

[darrelmiller]

Only allowing two media types makes no sense to me, especially considering we claim to allow wildcards. Considering the JSON schema mentions media-range my guess is that we were expecting to support this https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1 media-range here.

[mikekistler]

I think what was meant here is:

The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of values that can be either a specific media type or a wildcard media type.

[handrews]

@mikekistler I'm 99.999% sure that's the same as saying a list of media-ranges (as is taken by the Accept header). However we describe it for the Responses Object, we should probably do the same here.

[mikekistler]

My reading of the BNF:

media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) *( OWS
    ";" OWS parameter )

(and I certainly claim no expertise here) is that a "media range" can be either a specific "type/subtype" or a wildcard type with an "*" for either the subtype or both type and subtype. If that's right, then I agree that we only need to talk about "media types" and what was intended in the section in question is just a list of "media ranges".

[handrews]

After a great deal of GitHub archaeology, I have determined the "two types" in question are "regular media types" and "wildcard media types", and not a limit on the list:

• b00d081#r122329498 (note example with three entries in the discussion thread)

However, media-range is not suitable as it includes parameters, which were definitely not included in the discussion above. I'd suggest that we ought to consider media ranges in 3.2, but we already have trouble working with HTTP header parameter.

Anyway, this will get addressed in a new PR that is more comprehensive than the one I closed after @ralfhandl spotted that it wouldn't work.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!