From ce6c1781216a8da6f156315133634068db2ef278 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 30 Mar 2017 12:09:42 -0700 Subject: [PATCH 1/2] Prefix "schema" and "encType" with "submission" These "schema" keyword is too generic of a name given that there are now three schemas involved in an LDO. Change it to indicate that it is used for submitting data for processing, as is done with HTML form submissions. Rename "encType" to match. --- jsonschema-hyperschema.xml | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index dbfb826f..4b1e9bb6 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -390,15 +390,15 @@
- "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. + "Form"-like functionality can be defined by use of the "method" and "submissionSchema" 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 + 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 "schema", allows resolving + 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. @@ -407,7 +407,7 @@ data to resolve the template, and falls back to resolving any remaining variables from the instance. - A link with a "schema" allows submitting external data either as a request body (if "method" is "post"), + A link with a "submissionSchema" 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. @@ -580,7 +580,7 @@ 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. + which would allow the concurrent use of "submissionSchema" on a "post" link.
@@ -702,7 +702,7 @@ GET /foo/ -
+
This property provides a schema that is expected to describe the link target's representation. Depending on the protocol, @@ -883,7 +883,7 @@ GET /foo/
-
+
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. @@ -894,10 +894,10 @@ 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 encoded 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 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 +1058,9 @@ 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" From 7ecfdb46e3eee6d4cc14106fc4080b0a1c9166ff Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 30 Mar 2017 12:12:03 -0700 Subject: [PATCH 2/2] Remove "method", add "form". This removes the "method" keyword and reworks all references to HTML forms. The difference in approach between JSON Hyper-Schema and HTML+JavaScript is explained, and the different sorts of links (in terms of data usage) are described. The "form" keyword is being added to indicate HTML POST form semantics. GET forms can be simulated with "hrefSchema", and the guidance on that has been made more clear. We also now clearly acknowldege that you cannot directly specify HTML methods, as that was the largest source of confusion in the feedback to the previous draft. --- jsonschema-hyperschema.xml | 188 ++++++++++++++++++++++++------------- 1 file changed, 121 insertions(+), 67 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 4b1e9bb6..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 "submissionSchema" 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 "submissionSchema". 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 "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. + 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 "submissionSchema" 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 "submissionSchema" 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. @@ -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 @@ -937,7 +984,6 @@ GET /foo/ - This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" 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 "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 "submissionSchema" which describes the user-submitted request data to be evaluated by the resource. @@ -1061,6 +1114,7 @@ GET /foo/ Clarified HTTP use with "targetSchema" Renamed "schema" to "submissionSchema" Renamed "encType" to "submissionEncType" + Removed "method", add "form" for HTML "post" form semantics