Encoding Obj contentType takes a media range (3.0.4) #3813
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The "the two types" appears to have come from an example involving two types, and the TSC agrees that there was no intention to limit it to two. The syntax described also matches media type ranges, which is what is used for keys under `content` keywords that take objects of Media Type Objects. As that is analogous to the use of `contentType` in the Encoding Object, this change aligns the wording. The guidance on default values was difficult to format in a readable way inside of the fixed fields table, so this change also moves it to its own table.
handrews
added
clarification
ralfhandl
requested changes
May 17, 2024
| @@ -1601,14 +1601,25 @@ A single encoding definition applied to a single schema property. | |||
| ##### Fixed Fields | |||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="encodingContentType"></a>contentType | `string` | 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. | |||
| <a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below. | |||
There was a problem hiding this comment.
Suggested change
| <a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below. | |
| <a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. The value is a comma-separated list of [media type ranges](https://tools.ietf.org/html/rfc7231#appendix-D). Default value depends on the property type as shown in the table below. |
Note: rule media-range is only a single thingy, and it includes non-wildcard type "/" subtype as an alternative.
We can't take away the "list of" in a patch version.
There was a problem hiding this comment.
@ralfhandl there is no intention to take away anything. This is what we thought made sense in a TDC call, so either it was supposed to be "list of media-ranges" or something else.
I think perhaps what we want is list of media-ranges-without-parameters, because that's what the previous awkward wording (aside from the "the two types" part) described.
|
Converting to draft because I did some deeper digging and this is murkier than expected. |
|
OK on second thought I'm closing this and starting over. @ralfhandl thanks for catching the un-intended removal of list-ness, sadly there's more complex history here as well. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes:
contentTypefield: "comma-separated list of the two types"? #3739The "the two types" appears to have come from an example involving two types, and the TSC agrees that there was no intention to limit it to two. The syntax described also matches media type ranges, which is what is used for keys under
contentkeywords that take objects of Media Type Objects. As that is analogous to the use ofcontentTypein the Encoding Object, this change aligns the wording.The guidance on default values was difficult to format in a readable way inside of the fixed fields table, so this change also moves it to its own table.