diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index dbfb826f..e63b2ada 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -10,7 +10,7 @@ - + ]> @@ -388,35 +388,93 @@ The URI of the normative link description schema is: http://json-schema.org/draft-04/links (draft-04 version). -
+
- "Form"-like functionality can be defined by use of the "method" and "schema" keywords, which supplies a schema describing the data to supply to the server. - 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 "schema". This does not - allow for any variance in the link URI, nor does it allow for a request document. + + 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). + - An "href" with at least one template variable, but no "hrefSchema" or "schema", allows resolving - the template variable from the instance, but does not allow resolving it - from external data, nor does it allow a request document. + Link Description Objects do not directly indicate what operations, such + as HTTP methods for links with "http(s)://" URI schemes, are supported by + the target resource. Instead, operations should be inferred primarily from + link relation types and URI schemes. Additionally, + the presence of keywords related to data use often implies support for certain + operations. Note, however, that a resource may always decline an operation at + runtime, for instance due to application state that controls the operation's + availability. - 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. + 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 client input + 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 + - A link with a "schema" allows submitting external data either as a request body (if "method" is "post"), - or as a URI query string (if "method" is "get"). Such a query string replaces any query string - present after the "href" template is resolved. + In the human-oriented web, these cases are implemented through + a combination of HTML and JavaScript. The relatively rapid evolution + and broad adoption of JavaScript reduced the need to include all + features in HTML itself. - See the individual keyword descriptions below for details related to each of these cases. + Since JSON Hyper-Schema addresses all of these cases, and is consumed + primarily by client code rather than human users, its mechanisms do not + exactly match those of HTML. Instead, three schema keywords describe + the different kinds of input. Unless otherwise specified, schema keywords + are ignored when performing operations to which they are not semantically + relevant. +
+ + 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 + for client data, forbid it, or allow client data while falling back to + server-supplied instance data if no client data is provided. + + + This offers a superset of traditional HTML GET forms, and a subset of all + possible URI construction that can be performed by JavaScript. To simulate + an HTML GET form, a link can require client input to all query string variables, + and forbid client input for all other template variables. + +
+
+ + HTML does not directly support target resource representation manipulation + through forms. Instead, JavaScript accomplishes this by intercepting the + form submission and using the appropriate HTTP request with the form data. + In JSON Hyper-Schema, "targetSchema" + supplies a non-authoritative description of the target resource's representation. + A client can use "targetSchema" to structure input, or (if it is absent or + if the client prefers to only use authoritative information), interact with + the target resource to confirm or discover its representation structure. + +
+
+ + The "submissionSchema" and + "submissionEncType" keywords + describe the domain of the processing function implemented by the target resource. + This directly corresponds to HTML "method"="post" forms. + The "form" + keyword can be used to enforce strict semantic compatibility with HTML "post" + forms, limiting operations to those that make use of the submission data. + Otherwise, as noted above, the submission schema and encoding are ignored + for operations to which they are not relevant. + +
- +
@@ -512,6 +570,10 @@ months for date-time input but using the standard date-time format for storage. + + Omitting this keyword has the same behavior as a schema of false, + which forbids all external data input. +
For example, this defines a schema for each of the query string @@ -579,13 +641,13 @@
- The above example simulates the behavior found in earlier drafts using only "hrefSchema", - which would allow the concurrent use of "schema" on a "post" link. + The above example simulates the HTML GET form behavior found in earlier drafts + using only "hrefSchema", which is necessary now that "method" has been removed.
-
+
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. @@ -702,7 +764,7 @@ GET /foo/
-
+
This property provides a schema that is expected to describe the link target's representation. Depending on the protocol, @@ -863,69 +925,54 @@ GET /foo/
-
+
- The following properties also apply to Link Description Objects, and provide functionality analogous to HTML forms, by providing a means for making a request with client- or user-selected information. + The following properties also apply to Link Description Objects, + and provide the ability to describe data for submission to the + target resource for processing, independent of manipulating the + target resource's representation. -
+
+ + The value of this keyword is a boolean. + - This property specifies that the client can construct a templated query or non-idempotent request to a resource. + Setting this keyword to true indicates that this link has + semantics analogous to + HTML "method"="post" forms. + This imposes additional constraints that are not present if + the value of this keyword is false. - If "method" is "get", the link identifies how a user can compute the URI of an arbitrary resource. For example, how to compute a link to a page of search results relating to the instance, for a user-selected query term. Despite being named after GET, there is no constraint on the method or protocol used to interact with the remote resource. + In particular, if "form" is true, request payloads SHOULD conform + to "submissionSchema" + and "submissionEncType", + and the link MUST NOT be used with operations that are incompatible + with those semantics. - If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation. + Note that "hrefSchema" already offers a superset + of the functionality of HTML GET forms, so there is no explicit + analogue for that aspect of HTML. - Values for this property SHOULD be lowercase, and SHOULD be compared case-insensitive. Use of other values not defined here SHOULD be ignored. + Omitting this keyword has the same behavior as a value of false.
-
+
- If present, this property indicates the media type format the client should use to encode a query parameter or send to the server. - If the method is "get", this will indicate how to encode the query-string that is appended to the "href" link target. - If the method is "post", this indicates which media type to send to the server and how to encode it. - -
- For example, with the following schema: - - - - This indicates that the client can query the server for instances that have a specific name. -
- -
- For example: - - - -
+ If present, this property indicates which media type to use + when sending data matching the + "submissionSchema" + to the target resource for processing, and how to encode it. - If the method is "post", "application/json" is the default media type. + Omitting this keyword has the same behavior as a value of + "application/json". - As noted under method, these fields - are not restricted to HTTP URIs. -
For example, this link indicates that if you want to @@ -936,8 +983,7 @@ GET /foo/
-
+
- This property contains a schema which defines the acceptable structure of the document being encoded according to the "encType" property. + This property contains a schema which defines the + acceptable structure of the document being submitted + for processing by + according to the "submissionEncType" property. - Note that this does not define the structure for URI template variables. That is handed by "hrefSchema". If the method is "get" and the resolved URI Template has a query string, the query string produced by input validated against "schema" replaces the existing query string. + Note that this does not define the structure for URI template variables. That is handed by "hrefSchema". If the method is "get" and the resolved URI Template has a query string, the query string produced by input validated against "submissionSchema" replaces the existing query string. + + + This can be viewed as describing the domain of the processing + function implemented by the target resource. - This is a separate concept from the "targetSchema" property, which is describing the target information resource (including for replacing the contents of the resource in a PUT request), unlike "schema" which describes the user-submitted request data to be evaluated by the resource. + This is a separate concept from the "targetSchema" property, which is describing the target information resource (including for replacing the contents of the resource in a PUT request), unlike "submissionSchema" which describes the user-submitted request data to be evaluated by the resource. + "submissionSchema" is intended for use with requests that have payloads that are not + defined in terms of the target representation.
@@ -1056,6 +1111,10 @@ GET /foo/ Removed URI Template pre-processing Clarified how links and data submission work Clarified how validation keywords apply hyper-schema keywords and links + Clarified HTTP use with "targetSchema" + Renamed "schema" to "submissionSchema" + Renamed "encType" to "submissionEncType" + Removed "method", add "form" for HTML "post" form semantics