Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
handrews opened this issue Apr 23, 2024 · 9 comments
Closed
Assignees
Labels
media and encoding Issues regarding media type support and how to encode data (outside of query/path params) question
Milestone

Comments

@handrews
Copy link
Member

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 binaryapplication/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.

@handrews handrews added question media and encoding Issues regarding media type support and how to encode data (outside of query/path params) labels Apr 23, 2024
@handrews handrews added this to the v3.0.4 milestone Apr 23, 2024
@karenetheridge
Copy link
Member

karenetheridge commented Apr 25, 2024

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
Copy link
Member Author

"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
Copy link
Member Author

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

@darrelmiller
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member Author

handrews commented May 6, 2024

@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.

@handrews handrews removed the review label May 6, 2024
@handrews handrews self-assigned this May 6, 2024
@mikekistler
Copy link
Contributor

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
Copy link
Member Author

handrews commented May 19, 2024

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:

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
Copy link
Member Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
media and encoding Issues regarding media type support and how to encode data (outside of query/path params) question
Projects
None yet
Development

No branches or pull requests

4 participants