diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 36b7bfb7..b3230076 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -387,38 +387,87 @@ The URI of the normative link description schema is: http://json-schema.org/draft-04/links (draft-04 version). -
+
- Data input functionality can be defined by use of the - "submissionSchema" and - "submissionEncType" keywords, - which supply a description of data to send to the target resource for processing. - Functionality equivalent to dynamic URI generation is available through - the "href" template and - "hrefSchema". - - - The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not - allow for any variance in the link URI, nor does it allow for a request document. - - - An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving - the template variable from the instance, but does not allow resolving it - from external data, nor does it allow a request document. - - - An "href" with at least one template variable and with an "hrefSchema" allows using external - data to resolve the template, and falls back to resolving any remaining variables from the instance. + + Note that while the current draft does not provide a way to explicity + indicate HTTP method support, some way of providing a non-authoritative + hint may be added in a future draft (see issue #73 in the GitHub repository). + - A link with a "submissionSchema" allows submitting data for processing. + There are several ways that a client can use data can with a link: + + URI Template variables resolved from server-supplied 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 + + 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. - See the individual keyword descriptions below for details related to each of these cases. + Link Description Objects do not directly indicate what operations, such + as HTTP methods, are supported by the target resource. Instead, operations + should be inferred primarily from link relation types + and URI schemes. Note, however, that a resource may always decline an operation at + runtime, for instance due to application state that controls the operation's + availability. +
+ + URI Template variables in "href" resolve from + server-supplied 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 + from user agent data, forbid it, or allow user agent data while falling back 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 + 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 + that the path variables can only be resolved from the instance, and the + query string variables can only be resolved from user agent data. + See the "hrefSchema" section for an example of this approach. + +
+
+ + In JSON Hyper-Schema, "targetSchema" + supplies a non-authoritative description of the 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 can + interact with the target resource to confirm or discover its representation + structure. + + + "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. + +
+
+ + 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. + +
- +
@@ -442,7 +491,7 @@
The URI Template is filled out using data from some combination of an external source and the instance. - Where either instance data or external data may be used, this section will refer simply to "data" or to a "value". + 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. To allow the use of any object property (including the empty string) or array index, the following rules are defined: @@ -458,10 +507,10 @@ If "hrefSchema" is present and - external input is provided, the input MUST be a valid instance according + user agent data is provided, the data MUST be a valid instance according to the value of "hrefSchema". Template variables, after the process listed above, MUST first - be resolved from the external data instance. Any variables left + be resolved from the user agent data instance. Any variables left unresolved MUST be resolved from the resource instance data. @@ -484,11 +533,11 @@
Sometimes, the appropriate values will not be available. - For example, the template might specify the use of object properties, but no such input was provide (or "hrefSchema" is not present), and the instance is an array or a string. + For example, the template might specify the use of object properties, but no such data was provided (or "hrefSchema" is not present), and the instance is an array or a string. - If any of the values required for the template are present in neither the user input (if relevant) or the JSON instance, then substitute values MAY be provided from another source (such as default values). + 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). Otherwise, the link definition SHOULD be considered not to apply to the instance.
@@ -500,17 +549,17 @@ The value of the "hrefSchema" link description property MUST be a valid JSON Schema. This schema is used to validate user input - or other external data for filling out the URI Template in + or other user agent data for filling out the URI Template in "href", as described in that section. Omitting "hrefSchema" or setting the entire schema to "false" prevents - any external data from being accepted. + any user agent data from being accepted. Implementations MUST NOT attempt to validate values resolved from resource instance data with "hrefSchema". This allows for different - validation rules for user input, such as supporting spelled-out + 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. @@ -544,9 +593,9 @@
In this example, the schema for "extra" is given as a reference - to keep the external data validation constraints identical to the + to keep the user agent data validation constraints identical to the instance validation constraints for the corresponding property, - while "id" is given a false schema to prevent external data for + while "id" is given a false schema to prevent user agent data for that variable. @@ -587,7 +636,7 @@
-
+
The value of the "rel" property indicates the name of the relation to the 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. @@ -711,7 +760,7 @@ GET /foo/ the schema may or may not describe the response to any particular request sent to the link. This property is advisory only. -
+
The relationship between a resource's representation and HTTP requests and responses is determined by @@ -868,7 +917,7 @@ GET /foo/
If present, this property indicates the media type format the - client should use to for the request payload described by + client should use for the request payload described by "submissionSchema". @@ -935,7 +984,7 @@ GET /foo/ Omitting "submissionSchema" or setting the entire schema to "false" prevents - any external data from being accepted. + any user agent data from being accepted.