Skip to content

Moving "media" into validation (as "contentEncoding"+"contentMediaType") #384

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.

Sign up for GitHub

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

Merged
merged 6 commits into from
Sep 14, 2017
Merged

Moving "media" into validation (as "contentEncoding"+"contentMediaType") #384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4671d7a
Move "media" from Hyper-Schema into Validation as "contentEncoding"+"…
dlax Aug 28, 2017
1ae197a
Drop "description" from content{MediaType,Encoding} in meta-schema
dlax Aug 31, 2017
29b7b46
Move media from Hyper-Schema as contentMediaType/contentEncoding in V…
dlax Aug 28, 2017
24f81c2
Cleanup Hyper-Schema from left-over examples/wordings about "media"
dlax Aug 31, 2017
0d205ae
Add an "Implementation requirements" section for content{Encoding,Med…
Sep 1, 2017
e1116ab
Merge branch 'master' into media-in-validation
handrews Sep 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 0 additions & 11 deletions hyper-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,17 +57,6 @@
"items": {
"$ref": "http://json-schema.org/draft-06/links#"
}
},
"media": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"binaryEncoding": {
"type": "string"
}
}
}
},
"links": [
Expand Down
133 changes: 4 additions & 129 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY rfc2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
Expand Down Expand Up @@ -123,8 +122,6 @@
<t>
This document describes how JSON Schema can be used to define hyperlinks on instance
data.
It also defines how to provide additional information required to interpret JSON
data as rich multimedia documents.
</t>
<t>
As with all JSON Schema keywords, all the keywords described in the "Schema
Expand All @@ -133,8 +130,7 @@
</t>
<figure>
<preamble>
Here is an example JSON Schema defining hyperlinks, and providing a multimedia
interpretation for the "imgData" property:
Here is an example JSON Schema defining hyperlinks:
</preamble>
<artwork>
<![CDATA[
Expand All @@ -153,14 +149,6 @@
},
"authorId": {
"type": "integer"
},
"imgData": {
"title": "Article Illustration (thumbnail)",
"type": "string",
"media": {
"binaryEncoding": "base64",
"type": "image/png"
}
}
},
"required" : ["id", "title", "authorId"],
Expand All @@ -178,11 +166,8 @@
]]>
</artwork>
<postamble>
This example schema defines the properties of the instance. For the "imgData"
property, it specifies that that it should be base64-decoded and the resulting
binary data treated as a PNG image.
It also defines link relations for the instance, with URIs incorporating values
from the instance.
This example schema defines the properties of the instance as well as link
relations for the instance, with URIs incorporating values from the instance.
<cref>
"id" probably should not normally be a required keyword, since new instances
will have an unknown "id" property until is it assigned by the server.
Expand All @@ -192,25 +177,6 @@
</postamble>
</figure>

<figure>
<preamble>
An example of a JSON instance described by the above schema might be:
</preamble>
<artwork>
<![CDATA[
{
"id": 15,
"title": "Example data",
"authorId": 105,
"imgData": "iVBORw...kJggg=="
}
]]>
</artwork>
<postamble>
The base-64 data has been abbreviated for readability.
</postamble>
</figure>

<section title="Interaction with validation">
<t>
Hyper-schema keywords can be applied when the instance is valid against
Expand Down Expand Up @@ -338,94 +304,6 @@
</figure>
</section>

<section title="media">
<t>
The "media" property indicates that this instance contains non-JSON data encoded
in a JSON string.
It describes the type of content and how it is encoded.
</t>
<t>
The value of this property MUST be an object.
The value of this property SHOULD be ignored if the instance described is not a
string.
</t>

<section title="Properties of &quot;media&quot;">
<t>
The value of the "media" keyword MAY contain any of the following
properties:
</t>

<section title="binaryEncoding">
<t>
If the instance value is a string, this property defines that the string
SHOULD be interpreted as binary data and decoded using the encoding
named by this property.
<xref target="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible
values for this property.
</t>
</section>

<section title="type">
<t>
The value of this property must be a media type, as defined by
<xref target="RFC2046">RFC 2046</xref>. This property defines the media
type of instances which this schema defines.
</t>

<t>
If the "binaryEncoding" property is not set, but the instance value is a
string, then the value of this property SHOULD specify a text document
type, and the character set SHOULD be the character set into which the
JSON string value was decoded (for which the default is Unicode).
</t>
</section>
</section>

<section title="Example">
<figure>
<preamble>
Here is an example schema, illustrating the use of "media":
</preamble>
<artwork>
<![CDATA[
{
"type": "string",
"media": {
"binaryEncoding": "base64",
"type": "image/png"
}
}
]]>
</artwork>
<postamble>
Instances described by this schema should be strings, and their values
should be interpretable as base64-encoded PNG images.
</postamble>
</figure>

<figure>
<preamble>
Another example:
</preamble>
<artwork>
<![CDATA[
{
"type": "string",
"media": {
"type": "text/html"
}
}
]]>
</artwork>
<postamble>
Instances described by this schema should be strings containing HTML,
using whatever character set the JSON string was decoded into (default
is Unicode).
</postamble>
</figure>
</section>
</section>
</section>

<section title="Link Description Object">
Expand Down Expand Up @@ -1010,9 +888,7 @@ GET /foo/
"properties": {
"message": {
"description": "Re-interpret `message` as HTML",
"media": {
"type": "text/html"
}
"contentMediaType": "text/html"
}
}
}
Expand Down Expand Up @@ -1310,7 +1186,6 @@ GET /foo/
<back>
<!-- References Section -->
<references title="Normative References">
&rfc2045;
&rfc2119;
&rfc3986;
<!--&rfc4287;-->
Expand Down
114 changes: 114 additions & 0 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC1034 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1034.xml">
<!ENTITY RFC2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2673 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2673.xml">
<!ENTITY RFC3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
Expand Down Expand Up @@ -993,6 +995,116 @@
</section>
</section>

<section title='String-encoding non-JSON data'>

<section title="Foreword">
<t>
Properties defined in this section indicate that an instance contains
non-JSON data encoded in a JSON string.
They describe the type of content and how it is encoded.
</t>
<t>
These properties provide additional information required to interpret JSON data
as rich multimedia documents.
</t>
</section>

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the reason / use case for this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

for these keywords.
</t>
</section>

<section title="contentEncoding">

<t>
If the instance value is a string, this property defines that the string
SHOULD be interpreted as binary data and decoded using the encoding
named by this property.
<xref target="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible
values for this property.
</t>

<t>
The value of this property MUST be a string.
</t>

<t>
The value of this property SHOULD be ignored if the instance described is not a
string.
</t>

</section>

<section title="contentMediaType">
<t>
The value of this property must be a media type, as defined by
<xref target="RFC2046">RFC 2046</xref>. This property defines the media
type of instances which this schema defines.
</t>

<t>
The value of this property MUST be a string.
</t>

<t>
The value of this property SHOULD be ignored if the instance described is not a
string.
</t>

<t>
If the "contentEncoding" property is not present, but the instance value is a
string, then the value of this property SHOULD specify a text document type,
and the character set SHOULD be the character set into which the JSON string
value was decoded (for which the default is Unicode).
</t>
</section>

<section title="Example">
<figure>
<preamble>
Here is an example schema, illustrating the use of "contentEncoding" and
"contentMediaType":
</preamble>
<artwork>
<![CDATA[
{
"type": "string",
"contentEncoding": "base64",
"contentMediaType": "image/png"
}
]]>
</artwork>
<postamble>
Instances described by this schema should be strings, and their values
should be interpretable as base64-encoded PNG images.
</postamble>
</figure>

<figure>
<preamble>
Another example:
</preamble>
<artwork>
<![CDATA[
{
"type": "string",
"contentMediaType": "text/html"
}
]]>
</artwork>
<postamble>
Instances described by this schema should be strings containing HTML, using
whatever character set the JSON string was decoded into (default is
Unicode).
</postamble>
</figure>
</section>

</section>

<section title="Security considerations">
<t>
JSON Schema validation defines a vocabulary for JSON Schema core and concerns all
Expand Down Expand Up @@ -1034,6 +1146,8 @@

<references title="Informative References">
&RFC1034;
&RFC2045;
&RFC2046;
&RFC2673;
&RFC3339;
&RFC3986;
Expand Down
2 changes: 2 additions & 0 deletions schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,8 @@
]
},
"format": { "type": "string" },
"contentMediaType": { "type": "string" },
"contentEncoding": { "type": "string" },
"if": {"$ref": "#"},
"then": {"$ref": "#"},
"else": {"$ref": "#"},
Expand Down