Skip to content

Commit c23e0b6

Browse files
dlaxdlax
committed
Move media from Hyper-Schema as contentMediaType/contentEncoding in Validation
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 #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.
1 parent b918ab1 commit c23e0b6

File tree

2 files changed

+103
-92
lines changed

2 files changed

+103
-92
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 1 addition & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
<?xml version="1.0" encoding="US-ASCII"?>
22
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
3-
<!ENTITY rfc2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
43
<!ENTITY rfc2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
54
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
65
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
@@ -337,95 +336,6 @@
337336
</figure>
338337
</section>
339338

340-
<section title="media">
341-
<t>
342-
The "media" property indicates that this instance contains non-JSON data encoded
343-
in a JSON string.
344-
It describes the type of content and how it is encoded.
345-
</t>
346-
<t>
347-
The value of this property MUST be an object.
348-
The value of this property SHOULD be ignored if the instance described is not a
349-
string.
350-
</t>
351-
352-
<section title="Properties of &quot;media&quot;">
353-
<t>
354-
The value of the "media" keyword MAY contain any of the following
355-
properties:
356-
</t>
357-
358-
<section title="binaryEncoding">
359-
<t>
360-
If the instance value is a string, this property defines that the string
361-
SHOULD be interpreted as binary data and decoded using the encoding
362-
named by this property.
363-
<xref target="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible
364-
values for this property.
365-
</t>
366-
</section>
367-
368-
<section title="type">
369-
<t>
370-
The value of this property must be a media type, as defined by
371-
<xref target="RFC2046">RFC 2046</xref>. This property defines the media
372-
type of instances which this schema defines.
373-
</t>
374-
375-
<t>
376-
If the "binaryEncoding" property is not set, but the instance value is a
377-
string, then the value of this property SHOULD specify a text document
378-
type, and the character set SHOULD be the character set into which the
379-
JSON string value was decoded (for which the default is Unicode).
380-
</t>
381-
</section>
382-
</section>
383-
384-
<section title="Example">
385-
<figure>
386-
<preamble>
387-
Here is an example schema, illustrating the use of "media":
388-
</preamble>
389-
<artwork>
390-
<![CDATA[
391-
{
392-
"type": "string",
393-
"media": {
394-
"binaryEncoding": "base64",
395-
"type": "image/png"
396-
}
397-
}
398-
]]>
399-
</artwork>
400-
<postamble>
401-
Instances described by this schema should be strings, and their values
402-
should be interpretable as base64-encoded PNG images.
403-
</postamble>
404-
</figure>
405-
406-
<figure>
407-
<preamble>
408-
Another example:
409-
</preamble>
410-
<artwork>
411-
<![CDATA[
412-
{
413-
"type": "string",
414-
"media": {
415-
"type": "text/html"
416-
}
417-
}
418-
]]>
419-
</artwork>
420-
<postamble>
421-
Instances described by this schema should be strings containing HTML,
422-
using whatever character set the JSON string was decoded into (default
423-
is Unicode).
424-
</postamble>
425-
</figure>
426-
</section>
427-
</section>
428-
429339
<section title="readOnly">
430340
<t>
431341
If it has a value of boolean true, this keyword indicates that the value of the
@@ -963,7 +873,7 @@ GET /foo/
963873
"properties": {
964874
"message": {
965875
"description": "Re-interpret `message` as HTML",
966-
"media": {
876+
"contentMediaType": {
967877
"type": "text/html"
968878
}
969879
}
@@ -1184,7 +1094,6 @@ GET /foo/
11841094
<back>
11851095
<!-- References Section -->
11861096
<references title="Normative References">
1187-
&rfc2045;
11881097
&rfc2119;
11891098
&rfc3986;
11901099
<!--&rfc4287;-->

‎jsonschema-validation.xml

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
<?xml version="1.0" encoding="US-ASCII"?>
22
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
33
<!ENTITY RFC1034 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1034.xml">
4+
<!ENTITY RFC2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml">
5+
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2046.xml">
46
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
57
<!ENTITY RFC2373 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2373.xml">
68
<!ENTITY RFC2673 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2673.xml">
@@ -899,6 +901,104 @@
899901
</section>
900902
</section>
901903

904+
<section title='String-encoding non-JSON data'>
905+
906+
<section title="Foreword">
907+
<t>
908+
Properties defined in this section indicate that an instance contains
909+
non-JSON data encoded in a JSON string.
910+
They describe the type of content and how it is encoded.
911+
</t>
912+
</section>
913+
914+
<section title="contentEncoding">
915+
916+
<t>
917+
If the instance value is a string, this property defines that the string
918+
SHOULD be interpreted as binary data and decoded using the encoding
919+
named by this property.
920+
<xref target="RFC2045">RFC 2045, Sec 6.1</xref> lists the possible
921+
values for this property.
922+
</t>
923+
924+
<t>
925+
The value of this property MUST be a string.
926+
</t>
927+
928+
<t>
929+
The value of this property SHOULD be ignored if the instance described is not a
930+
string.
931+
</t>
932+
933+
</section>
934+
935+
<section title="contentMediaType">
936+
<t>
937+
The value of this property must be a media type, as defined by
938+
<xref target="RFC2046">RFC 2046</xref>. This property defines the media
939+
type of instances which this schema defines.
940+
</t>
941+
942+
<t>
943+
The value of this property MUST be a string.
944+
</t>
945+
946+
<t>
947+
The value of this property SHOULD be ignored if the instance described is not a
948+
string.
949+
</t>
950+
951+
<t>
952+
If the "contentEncoding" property is not present, but the instance value is a
953+
string, then the value of this property SHOULD specify a text document type,
954+
and the character set SHOULD be the character set into which the JSON string
955+
value was decoded (for which the default is Unicode).
956+
</t>
957+
</section>
958+
959+
<section title="Example">
960+
<figure>
961+
<preamble>
962+
Here is an example schema, illustrating the use of "contentEncoding" and
963+
"contentMediaType":
964+
</preamble>
965+
<artwork>
966+
<![CDATA[
967+
{
968+
"type": "string",
969+
"contentEncoding": "base64",
970+
"contentMediaType": "image/png"
971+
}
972+
]]>
973+
</artwork>
974+
<postamble>
975+
Instances described by this schema should be strings, and their values
976+
should be interpretable as base64-encoded PNG images.
977+
</postamble>
978+
</figure>
979+
980+
<figure>
981+
<preamble>
982+
Another example:
983+
</preamble>
984+
<artwork>
985+
<![CDATA[
986+
{
987+
"type": "string",
988+
"contentMediaType": "text/html"
989+
}
990+
]]>
991+
</artwork>
992+
<postamble>
993+
Instances described by this schema should be strings containing HTML, using
994+
whatever character set the JSON string was decoded into (default is
995+
Unicode).
996+
</postamble>
997+
</figure>
998+
</section>
999+
1000+
</section>
1001+
9021002
<section title="Security considerations">
9031003
<t>
9041004
JSON Schema validation defines a vocabulary for JSON Schema core and concerns all
@@ -940,6 +1040,8 @@
9401040

9411041
<references title="Informative References">
9421042
&RFC1034;
1043+
&RFC2045;
1044+
&RFC2046;
9431045
&RFC2373;
9441046
&RFC2673;
9451047
&RFC3339;

0 commit comments

Comments
 (0)