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

Activity

1. handrews commented on Apr 10, 2026

   

   handrews

   on Apr 10, 2026

   Member

   More actions

   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.

   😕React with 😕1Reacted by nocluemicheal
2. karenetheridge

   changed the title [-]vX.2: ambiguity/error with documentation of contentType in the encoding object[/-] [+]v3.2: ambiguity/error with documentation of contentType in the encoding object[/+] on Apr 10, 2026
3. karenetheridge commented on Apr 11, 2026

   

   karenetheridge

   on Apr 11, 2026

   MemberAuthor

   More actions

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

   It's not the same problem because when matching against the content field, we have a type to match with, from the Content-Type header. But when we're looking at contentType in the encoding object, we don't know what media-type we should be decoding as.

   "typically only one of them will be valid" -- but we have no idea which one.

   Specifically: Say we have a contentType field with value "image/jpeg, image/png, image/", and we know how to process "image/png" and "image/", what algorithm do we use for selecting which of those three contentType values to use for picking a decoder? Each of these three values needs to be tested against the two supported types and then some selection made.

   The easy thing to do is to always select the first one (image/jpeg) as long as we can match it against something (even if that's image/*), but I don't know if that's the most correct. image/png is an exact match, so should we pick that instead, even though it's not first in the list? And what if there are no exact matches at all - how do we select between them?

   I really don't understand the point of allowing multiple values in contentType here, as it's always going to be ambiguous.
4. handrews commented on Apr 11, 2026

   

   handrews

   on Apr 11, 2026

   Member

   More actions

   @karenetheridge

   It's not the same problem because when matching against the content field, we have a type to match with, from the Content-Type header. But when we're looking at contentType in the encoding object, we don't know what media-type we should be decoding as.

   Ah, I was thinking in terms of multipart, where you do have a per-part Content-Type. But your example is form-urlencoded where you do not.

   "typically only one of them will be valid" -- but we have no idea which one.

   Specifically: Say we have a contentType field with value "image/jpeg, image/png, image/*", and we know how to process "image/png" and "image/*", what algorithm do we use for selecting which of those three contentType values to use for picking a decoder? Each of these three values needs to be tested against the two supported types and then some selection made.

   I'm not sure how one would have a decoder for image/* as it literally means "any image media type", so I'm going to ignore that for now.

   PNG files start with a PNG signature, so if that's not present then you don't have a PNG. I suspect there is something similar to signify a JPEG, although I couldn't immediately find it. If there is, and the byte prefixes for PNG and JPEG are mutually exclusive, then you can definitely tell if you have a PNG vs a JPEG vs neither.

   If you can't, then the API designer has designed something that is, at least in some cases, impossible to sort out.

   This is also true if they use image/* in this way. There's no such thing as an "any image decoder." You just can't expect a tool to figure that out. Even with things like PNG prefixes, there will always only be a finite set that any one tool knows.

   The easy thing to do is to always select the first one (image/jpeg) as long as we can match it against something (even if that's image/*), but I don't know if that's the most correct. image/png is an exact match, so should we pick that instead, even though it's not first in the list? And what if there are no exact matches at all - how do we select between them?

   I'd say if you can't figure it out it's an error.

   I really don't understand the point of allowing multiple values in contentType here, as it's always going to be ambiguous.

   That's definitely not true, as the PNG signature shows. Also, application/json, application/xml is not ambiguous. It's going to be parseable as one or the other, and you'll figure out which very quickly.
5. handrews commented on Apr 11, 2026

   

   handrews

   on Apr 11, 2026

   Member

   More actions

   @karenetheridge really, I'm pretty sure this is mostly used for multipart, where there is a relevant per-part Content-Type header. If people try to do something too complicated to figure out with form-urlencoded then that's a user (meaning API designer / spec author) error.
6. karenetheridge commented on Apr 12, 2026

   

   karenetheridge

   on Apr 12, 2026

   MemberAuthor

   More actions

   I'm not sure how one would have a decoder for image/* as it literally means "any image media type", so I'm going to ignore that for now.

   The heuristic I'm using is "if a decoder isn't defined for a media-type, and the corresponding schema is not empty (i.e. not a boolean or an empty object), then generate a "failed to parse content" error. So, this allows for defining a decoder for "image/*" that just returns the bytestream as-is to bypass this error, and also allow for a schema like "maxLength": 20000 to indicate only small images are accepted.

   But, you did indicate a way forward I can use -- when multiple contentType values are provided, try the best-matching decoder for each one of them in sequence, and pick the first of these that does not error. So, the user can provide a more sophisticated image/png decoder that checks for the signature if they wish, or just use an identity function to accept any bytestream.
7. karenetheridge

   closed this as completedon Apr 12, 2026