diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 4b1e9bb6..4bc94371 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -10,7 +10,6 @@ - ]> @@ -390,8 +389,13 @@
- "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". + 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 @@ -407,9 +411,7 @@ data to resolve the template, and falls back to resolving any remaining variables from the instance. - 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. + A link with a "submissionSchema" allows submitting data for processing. See the individual keyword descriptions below for details related to each of these cases. @@ -579,8 +581,8 @@ - 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 behavior handled in earlier drafts + with a "method" of "get" by using the new "hrefSchema" keyword.
@@ -863,81 +865,30 @@ 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. + If present, this property indicates the media type format the + client should use to for the request payload described by + "submissionSchema". + + Omitting this keyword has the same behavior as a value of application/json. + + + Note that "submissionEncType" and "submissionSchema" + are not restricted to HTTP URIs. -
- - This property specifies that the client can construct a templated query or non-idempotent request to a resource. - - - 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. - - - If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation. - - - Values for this property SHOULD be lowercase, and SHOULD be compared case-insensitive. Use of other values not defined here SHOULD be ignored. - -
- -
- - 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 the method is "post", "application/json" is the default media type. - - - As noted under method, these fields - are not restricted to HTTP URIs. - -
- - For example, this link indicates that if you want to - send an email to the author of the context resource, - your client needs to ask for both a plain text - and an HTML representation. - - +
+ + For example, this link indicates that if you want to + send an email to the author of the context resource, + your client needs to ask for both a plain text + and an HTML representation. + + - -
- -
- -
- - 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 "submissionSchema" replaces the existing query string. - +
+ + This property contains a schema which defines the acceptable structure + of the document to be encoded according to the "submissionEncType" property + and sent to the target resource for processing. 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. - "submissionSchema" is intended for use with requests that have payloads that are not - defined in terms of the target representation. - -
+ + 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. + + + Omitting "submissionSchema" or setting the entire schema to "false" prevents + any external data from being accepted. +
@@ -1018,7 +972,6 @@ GET /foo/ &rfc5789; &rfc5988; &rfc7231; - &html5;
@@ -1061,6 +1014,7 @@ GET /foo/ Clarified HTTP use with "targetSchema" Renamed "schema" to "submissionSchema" Renamed "encType" to "submissionEncType" + Removed "method"