-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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 content and header clarifications (3.0.4) #3857
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks good
d4950d8
to
a4f3498
Compare
@notEthan @ralfhandl I'm afraid I did a little re-arranging after resolving conflicts because it got less clear. This now splits the fields like they are in the Parameter Object and the Header Object (now that both of those have their own tables structured the same way, the Encoding Object became a weird exception to the pattern). This will conflict with the percent-encoding PR, but it would have anyway. I'll resolve conflicts for whichever isn't merged first. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor nits
The Encoding Object's `contentType` field takes a comma-separated list of either regular or wildcared media types. These are the "two types" mentioned in the previous wording – "two" here did *not* refer to a limit on the number of entries in the list. These are not exactly media-type or media-range values, as both of those include parameters. This change also moves the hard-to-follow list of default values out of the individual field cell and into its own table. It takes `Content-Disposition` out of the header field's cell and instead explains limitations on header usage, and explains how `Content-Disposition` is used for encoding. This explanation includes a suggestion on how other `multipart` formats could be used with an Encoding Object, since their unnamed parts otherwise cannot be supported. Finally, it clarifies the interaction between `contentType` and the three fields imported from the Parameter Object, by aligning the recommended (but not, for compatibility reasons, required) behavior with guidance added in 3.1.0.
Co-authored-by: Ralf Handl <[email protected]>
Thanks to @notEthan for the comments!
This splits the Encoding Object's fixed fields table to make the usage more clear, and closer to how it is presented for the Parameter and Header Objects
🤦 thanks for catching this, @ralfhandl Co-authored-by: Ralf Handl <[email protected]>
Rendering with all currently open 3.0.4 changes (as of the timestamp of this edit - use the dropdown on the word "edited" in the bar for this comment) can be found here.
Fixes:
contentType
andstyle
/explode
/allowReserved
conflicts)contentType
field: "comma-separated list of the two types"? #3739 (by rephrasing how the comma-separated-list value ofcontentType
works)headers
can be usedThe Encoding Object's
contentType
field takes a comma-separated list of either regular or wildcared media types. These are the "two types" mentioned in the previous wording – "two" here did not refer to a limit on the number of entries in the list.These are not exactly media-type or media-range values, as both of those include parameters.
This change also moves the hard-to-follow list of default values out of the individual field cell and into its own table.
It takes
Content-Disposition
out of the header field's cell and instead explains limitations on header usage, and explains howContent-Disposition
is used for encoding.This explanation includes a suggestion on how other
multipart
formats could be used with an Encoding Object, since their unnamed parts otherwise cannot be supported.Finally, it clarifies the interaction between
contentType
and the three fields imported from the Parameter Object, by aligning the recommended (but not, for compatibility reasons, required) behavior with guidance added in 3.1.0.