Moving "media" into validation (as "contentEncoding"+"contentMediaType") #384
Conversation
There was a problem hiding this comment.
This looks great! I found one tiny leftover "media"-ism to fix.
Additionally, could you add an "Implementation requirements" section analogous to that for "format"? I think the requirements are similar- validators MAY validate some or all possible encodings/media types. But as that is likely to be burdensome if anything this should be an even weaker requirement than format. Mostly, these properties signal to applications how they can handle the field if it is a valid string to start with.
Unlike with "format", we won't be enumerating a set of supported media types, so no need to include the extensibility paragraph, I think.
jsonschema-hyperschema.xml
Outdated
| @@ -963,7 +873,7 @@ GET /foo/ | |||
| "properties": { | |||
| "message": { | |||
| "description": "Re-interpret `message` as HTML", | |||
| "media": { | |||
| "contentMediaType": { | |||
| "type": "text/html" | |||
There was a problem hiding this comment.
You no longer need the sub-field "type" here :-)
dlax
force-pushed
the
media-in-validation
branch
from
8f83782 to
f85ee90
Compare
|
@dlax can you rebase and fix the conflicts? @Relequestual does this change look good to you? Similar to the readOnly move, but I think less controversial because semantic description of content (as opposed to usage) pretty clearly belongs with |
dlax
force-pushed
the
media-in-validation
branch
from
f85ee90 to
fbd958c
Compare
| <section title="Implementation requirements"> | ||
| <t> | ||
| Implementations MAY support keywords defined in this section. | ||
| Should they choose to do so, they SHOULD offer an option to disable validation |
There was a problem hiding this comment.
What is the reason / use case for this?
There was a problem hiding this comment.
This is to mirror what's stated for "format" keyword (in "Implementation requirements" section). The reasoning is that "format" and "media*" keywords are semantically similar, so implementations should treat them similarly.
…contentMediaType"
None of other keywords have a description.
…alidation Definition of "media" property (an object in Hyper-Schema) is moved into two properties "contentMediaType" and "contentEncoding" in the validation specification. This addresses the other part of json-schema-org#363, which states that some keywords historically in the Hyper-Schema specification would be better in the Validation document. The main argument for moving keywords such as "media" is that the Hyper-Schema document could then only focus on describing the hypermedia linking model. The new keywords are described in a dedicated section "String-encoding non-JSON data". Part of the previous content was moved into a forewords section.
And move the sentence about "multimedia documents" back to Validation document where it still makes sense.
…iaType} Similar to the one of "format" keyword, without the extensibility note.
dlax
force-pushed
the
media-in-validation
branch
from
fbd958c to
0d205ae
Compare
Done. |
Addresses the other part of #363 (see also #378) by moving the "media" keyword into the validation document and splitting it into "contentEncoding"+"contentMediaType" in a (new) dedicated section similar to the one about "format".
All references to "multimedia" are also removed from the Hyper-Schema document. I kept most of the original textual content and examples as a first step.