From 4671d7a1d00c504af3ace449d97927b91a3dd926 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 10:22:17 +0200 Subject: [PATCH 1/5] Move "media" from Hyper-Schema into Validation as "contentEncoding"+"contentMediaType" --- hyper-schema.json | 13 ------------- schema.json | 8 ++++++++ 2 files changed, 8 insertions(+), 13 deletions(-) diff --git a/hyper-schema.json b/hyper-schema.json index 9f1a9385..dcd63325 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -109,19 +109,6 @@ "links": { "type": "array", "items": { "$ref": "#/definitions/linkDescription" } - }, - "media": { - "type": "object", - "properties": { - "type": { - "description": "A media type, as described in RFC 2046", - "type": "string" - }, - "binaryEncoding": { - "description": "A content encoding scheme, as described in RFC 2045", - "type": "string" - } - } } }, "links": [ diff --git a/schema.json b/schema.json index 1d31d8e4..b6d6f6b6 100644 --- a/schema.json +++ b/schema.json @@ -152,6 +152,14 @@ ] }, "format": { "type": "string" }, + "contentMediaType": { + "type": "string", + "description": "A media type, as described in RFC 2046" + }, + "contentEncoding": { + "type": "string", + "description": "A content encoding scheme, as described in RFC 2045" + }, "if": {"$ref": "#"}, "then": {"$ref": "#"}, "else": {"$ref": "#"}, From 1ae197a61d9f95751ccf87dd25a124fc6e20216e Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Thu, 31 Aug 2017 19:03:16 +0200 Subject: [PATCH 2/5] Drop "description" from content{MediaType,Encoding} in meta-schema None of other keywords have a description. --- schema.json | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/schema.json b/schema.json index b6d6f6b6..3c5b2981 100644 --- a/schema.json +++ b/schema.json @@ -152,14 +152,8 @@ ] }, "format": { "type": "string" }, - "contentMediaType": { - "type": "string", - "description": "A media type, as described in RFC 2046" - }, - "contentEncoding": { - "type": "string", - "description": "A content encoding scheme, as described in RFC 2045" - }, + "contentMediaType": { "type": "string" }, + "contentEncoding": { "type": "string" }, "if": {"$ref": "#"}, "then": {"$ref": "#"}, "else": {"$ref": "#"}, From 29b7b46dfb43f334a2d9897d886cf98d9a28d73c Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 17:22:10 +0200 Subject: [PATCH 3/5] 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. --- jsonschema-hyperschema.xml | 94 +--------------------------------- jsonschema-validation.xml | 102 +++++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 93 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 3e0cfcf4..8c890347 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1,6 +1,5 @@ @@ -337,94 +336,6 @@ -
- - 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. - - - 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. - - -
- - The value of the "media" keyword MAY contain any of the following - properties: - - -
- - 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. - RFC 2045, Sec 6.1 lists the possible - values for this property. - -
- -
- - The value of this property must be a media type, as defined by - RFC 2046. This property defines the media - type of instances which this schema defines. - - - - 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). - -
-
- -
-
- - Here is an example schema, illustrating the use of "media": - - - - - - Instances described by this schema should be strings, and their values - should be interpretable as base64-encoded PNG images. - -
- -
- - Another example: - - - - - - Instances described by this schema should be strings containing HTML, - using whatever character set the JSON string was decoded into (default - is Unicode). - -
-
-
@@ -1009,9 +920,7 @@ GET /foo/ "properties": { "message": { "description": "Re-interpret `message` as HTML", - "media": { - "type": "text/html" - } + "contentMediaType": "text/html" } } } @@ -1230,7 +1139,6 @@ GET /foo/ - &rfc2045; &rfc2119; &rfc3986; diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 0e9a5d37..1d9c6817 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -1,6 +1,8 @@ + + @@ -993,6 +995,104 @@
+
+ +
+ + 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. + +
+ +
+ + + 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. + RFC 2045, Sec 6.1 lists the possible + values for this property. + + + + The value of this property MUST be a string. + + + + The value of this property SHOULD be ignored if the instance described is not a + string. + + +
+ +
+ + The value of this property must be a media type, as defined by + RFC 2046. This property defines the media + type of instances which this schema defines. + + + + The value of this property MUST be a string. + + + + The value of this property SHOULD be ignored if the instance described is not a + string. + + + + 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). + +
+ +
+
+ + Here is an example schema, illustrating the use of "contentEncoding" and + "contentMediaType": + + + + + + Instances described by this schema should be strings, and their values + should be interpretable as base64-encoded PNG images. + +
+ +
+ + Another example: + + + + + + Instances described by this schema should be strings containing HTML, using + whatever character set the JSON string was decoded into (default is + Unicode). + +
+
+ +
+
JSON Schema validation defines a vocabulary for JSON Schema core and concerns all @@ -1034,6 +1134,8 @@ &RFC1034; + &RFC2045; + &RFC2046; &RFC2673; &RFC3339; &RFC3986; From 24f81c20ed2aedb6bc4f6dd2463b4a4d157b8b3c Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Thu, 31 Aug 2017 19:36:11 +0200 Subject: [PATCH 4/5] Cleanup Hyper-Schema from left-over examples/wordings about "media" And move the sentence about "multimedia documents" back to Validation document where it still makes sense. --- jsonschema-hyperschema.xml | 39 +++----------------------------------- jsonschema-validation.xml | 4 ++++ 2 files changed, 7 insertions(+), 36 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 8c890347..5e5c090c 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -121,8 +121,6 @@ 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. As with all JSON Schema keywords, all the keywords described in the "Schema @@ -131,8 +129,7 @@
- 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: - 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. "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. @@ -190,25 +176,6 @@
-
- - An example of a JSON instance described by the above schema might be: - - - - - - The base-64 data has been abbreviated for readability. - -
-
Hyper-schema keywords can be applied when the instance is valid against diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 1d9c6817..fc09aa86 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -1003,6 +1003,10 @@ non-JSON data encoded in a JSON string. They describe the type of content and how it is encoded. + + These properties provide additional information required to interpret JSON data + as rich multimedia documents. +
From 0d205aec68716820a5cc587ca506ef786e6e0b2d Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Fri, 1 Sep 2017 10:16:48 +0200 Subject: [PATCH 5/5] Add an "Implementation requirements" section for content{Encoding,MediaType} Similar to the one of "format" keyword, without the extensibility note. --- jsonschema-validation.xml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index fc09aa86..69f122d6 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -1009,6 +1009,14 @@
+
+ + Implementations MAY support keywords defined in this section. + Should they choose to do so, they SHOULD offer an option to disable validation + for these keywords. + +
+