From 242fef81db1fce63ebfa99baff76ebfebe9a8dde Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 22 Aug 2017 21:59:21 -0700 Subject: [PATCH 1/2] Reference validation from hyper-schema Despite having a whole section describing how hyper-schema builds on validation, it was never referenced or listed as a normative specifciation. Also, we had labled the meta-schema link as a validation schema in an apparent copy-paste error. Finally, improve wording around building on the other specs in the same way as was done for the validation spec referincing core. --- jsonschema-hyperschema.xml | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index ff85c4dd..efcf5d37 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -95,9 +95,10 @@ - This specification will use the terminology defined by the - JSON Schema core specification. It is advised that - readers have a copy of this specification. + This specification will use the concepts, syntax, and terminology defined by the + JSON Schema core and + JSON Schema validation specifications. + It is advised that readers have a copy of these specifications. @@ -234,7 +235,7 @@
- The current URI for the JSON Schema Validation is + The current URI for the JSON Hyper-Schema meta-schema is <http://json-schema.org/draft-06/hyper-schema#>.
@@ -464,7 +465,7 @@ - There are several ways that a client can use data can with a link: + There are several ways that a client can use data with a link: URI Template variables resolved from server-supplied instance data URI Template variables resolved from user agent data @@ -1188,7 +1189,17 @@ GET /foo/ - + + + + + JSON Schema Validation: A Vocabulary for Structural Validation of JSON + + + + + + From 49fd47c302b373dfbf5f9912a4b3abdf69b86501 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 22 Aug 2017 22:02:08 -0700 Subject: [PATCH 2/2] What is a JSON Hyper-Schema? This reworks the general descriptive text to emphasize how Hyper-Schema fits in to the RFC 5988 link model, or more accurately the RFC 5988bis revision currently in development. By presenting the Web Linking model as the central foundation for Hyper-Schema, and emphasizing the relationship between Hyper-Schema and the link context, the focus should be a bit more clearly on hypermedia rather than api request/responses. Also defined "operation" which I apparently just started using in that section without explaining it at all. --- jsonschema-hyperschema.xml | 104 +++++++++++++++++++++++++------------ 1 file changed, 70 insertions(+), 34 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index efcf5d37..483ec2eb 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -8,6 +8,7 @@ + ]> @@ -61,10 +62,12 @@ - JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords of JSON Schema - for annotating JSON documents with hyperlinks and instructions for processing and - manipulating remote JSON resources through hypermedia environments like HTTP. + JSON Schema is a JSON based format for working with the structure of JSON data. + + This document builds on the JSON Schema description of a context resource + by adding a templated link serialization format, along with + mechanisms for annotating the context resource with such links and + other information required to interpret JSON data as rich multimedia documents. @@ -87,7 +90,9 @@
JSON Schema is a JSON based format for defining the structure of JSON data. - This document specifies hyperlink- and hypermedia-related keywords of JSON Schema. + This document specifies a serialization of the link model defined in + , as well as keywords to associate such + link serializations and other hypermedia concepts with JSON data. The term JSON Hyper-Schema is used to refer to a JSON Schema that uses these @@ -116,12 +121,20 @@ The terms "schema" and "instance" are to be interpreted as defined in the JSON Schema core specification. + + + This specification uses the terms "link context" and "link target" as + defined in . These terms respectively + correspond with "Context IRI" and "Target IRI" as used in + RFC 5988. + Although defined as IRIs, in common scenarios they are also URIs. +
- This document describes how JSON Schema can be used to define hyperlinks on instance - data. + This document describes how JSON Schema can be used to define hyperlinks on + the instance data of a context resource. It also defines how to provide additional information required to interpret JSON data as rich multimedia documents. @@ -211,6 +224,10 @@
+ + Hyper-schema keywords are applied based on the validation outcome + of the link context, which is the instance resource. + Hyper-schemas MUST NOT be applied to an instance if the instance fails to validate against the validation keywords within or containing the hyper-schema. @@ -442,8 +459,17 @@
- A Link Description Object (LDO) is used to describe a single link relation from the - instance to another resource. + A Link Description Object (LDO) is a serialization of the abstract model specified + in Section 2 of , defines a link as + consisting of a "link context", a "link relation type", a "link target", + and optional "target attributes". + + + Additionally, LDOs can be used to define schemas for the link target, + the target's URI Template, or other data intended for submission over + the link. + + A Link Description Object must be an object. @@ -464,18 +490,24 @@ hint may be added in a future draft (see issue #73 in the GitHub repository). + + An operation is a specific use of a link described by an LDO, after any + template variables have been resolve. + There are several ways that a client can use data with a link: - URI Template variables resolved from server-supplied instance data + URI Template variables resolved from the link context instance data URI Template variables resolved from user agent data Replacing or modifying the target resource's representation Submitting data for processing, where the data has no - inherent relation to the target resource's representation + inherent relation to either the link context or the target resource's + representation The three ways to use client-supplied data are each addressed by a separate - schema keyword within the link description object. Link operations - ignore schemas that are not relevant to their semantics. + schema keyword within the link description object. When performing + operations, clients SHOULD ignore schemas that are not relevant to that + operation's semantics. Link Description Objects do not directly indicate what operations, such @@ -488,7 +520,7 @@
URI Template variables in "href" resolve from - server-supplied instance data by default. + the link context's instance data by default. "hrefSchema" allows a link to specify a schema for resolving template variables from client-supplied data. Regular JSON Schema validation features can be used to require resolution @@ -496,8 +528,8 @@ to server-supplied instance data if no user agent data is provided. - The common pattern of resolving a templated path component with - server-supplied instance data while accepting user agent data to build + The common pattern of resolving a templated path component with the + link context's instance data while accepting user agent data to build a query string can be implemented by setting the "hrefSchema" subschemas for the path template variables to false, while giving the query string template variables names that do not appear in the instance. This ensures @@ -509,7 +541,7 @@
In JSON Hyper-Schema, "targetSchema" - supplies a non-authoritative description of the target resource's + supplies a non-authoritative description of the link target resource's representation. A client can use "targetSchema" to structure input for replacing or modifying the representation. Alternatively, if "targetSchema" is absent or if the client prefers to only use authoritative information, it @@ -519,19 +551,20 @@ "targetSchema" is not intended to describe link operation responses, except when the response semantics indicate that it is a representation - of the target resource. In all cases, the schema indicated by the response - itself is authoritative. See the - for guidance - specific to each HTTP method when using "targetSchema" with HTTP URIs. + of the link target resource. In all cases, the schema indicated by + the response itself is authoritative. See the + for guidance specific to each HTTP method + when using "targetSchema" with HTTP URIs.
The "submissionSchema" and "submissionEncType" keywords - describe the domain of the processing function implemented by the target - resource. Otherwise, as noted above, the submission schema and encoding are - ignored for operations to which they are not relevant. + describe the domain of the processing function implemented by the + link target resource. Otherwise, as noted above, the submission schema + and encoding SHOULD be ignored for operations to which they are + not relevant.
@@ -541,8 +574,8 @@
The value of the "href" link description property is a template used to - determine the target URI of the related resource. - The value of the instance property MUST be resolved as a + determine the target URI of the link target resource. + The value of this property MUST be resolved as a URI-reference against the base URI of the instance. @@ -569,7 +602,7 @@
The URI Template is filled out using data from some combination of an - external source and the instance. + external source and the link context instance. Where either instance data or user agent data may be used, this section will refer simply to "data" or to a "value". When the source is important, it is specified explicitly. @@ -600,7 +633,7 @@ to the value of "hrefSchema". Template variables, after the process listed above, MUST first be resolved from the user agent data instance. Any variables left - unresolved MUST be resolved from the resource instance data. + unresolved MUST be resolved from the link context's instance data.
@@ -643,8 +676,9 @@ If any of the values required for the template are neither present in - the user agent data (if relevant) nor the JSON instance, then substitute - values MAY be provided from another source (such as default values). + the user agent data (if relevant) nor the link context instance, + then substitute values MAY be provided from another source + (such as default values). Otherwise, the link definition SHOULD be considered not to apply to the instance. @@ -666,7 +700,7 @@ Implementations MUST NOT attempt to validate values resolved from - resource instance data with "hrefSchema". This allows for different + link context instance data with "hrefSchema". This allows for different validation rules for user agent data, such as supporting spelled-out months for date-time input but using the standard date-time format for storage. @@ -746,14 +780,15 @@
- The value of the "rel" property indicates the name of the relation to the target + The value of the "rel" property indicates the name of the relation type from + the link's context resource to its target resource. The value MUST be a registered link relation from the IANA Link Relation Type Registry established in RFC 5988, or a normalized URI following the URI production of RFC 3986. - The relation to the target is interpreted as from the instance that the schema + The link context is interpreted as from the instance that the schema (or sub-schema) applies to, not any larger document that the instance may have been found in. @@ -978,7 +1013,7 @@ GET /foo/ The value of this property is advisory only, and represents the media type RFC 2046, that is expected to be returned when - fetching this resource. + fetching the link target resource. This property value MAY be a media range instead, using the same pattern defined in RFC 7231, section 5.3.2 - HTTP "Accept" header. @@ -1207,6 +1242,7 @@ GET /foo/ &rfc5789; &rfc5988; + &I-D.nottingham-rfc5988bis; &rfc7231;