Skip to content

Commit 7ecfdb4

Browse files
handrewshandrews
committed
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.
1 parent ce6c178 commit 7ecfdb4

File tree

1 file changed

+121
-67
lines changed

1 file changed

+121
-67
lines changed

‎jsonschema-hyperschema.xml

+121-67
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1111
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
1212
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
13-
<!ENTITY html5 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.CR-html5-20140731.xml">
13+
<!ENTITY html5 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html5-20141028.xml">
1414
]>
1515
<?rfc toc="yes"?>
1616
<?rfc symrefs="yes"?>
@@ -388,35 +388,93 @@
388388
The URI of the normative link description schema is: <eref target="http://json-schema.org/draft-04/links">http://json-schema.org/draft-04/links</eref> (draft-04 version).
389389
</t>
390390

391-
<section title="Links and data">
391+
<section title="Links, operations, and data">
392392
<t>
393-
"Form"-like functionality can be defined by use of the <xref target="method">"method"</xref> and <xref target="submissionSchema">"submissionSchema"</xref> keywords, which supplies a schema describing the data to supply to the server.
394-
Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>.
395-
</t>
396-
<t>
397-
The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not
398-
allow for any variance in the link URI, nor does it allow for a request document.
393+
<cref>
394+
Note that while the current draft does not provide a way to explicity
395+
indicate HTTP method support, some way of providing a non-authoritative
396+
hint may be added in a future draft (see issue #73 in the GitHub repository).
397+
</cref>
399398
</t>
400399
<t>
401-
An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving
402-
the template variable from the instance, but does not allow resolving it
403-
from external data, nor does it allow a request document.
400+
Link Description Objects do not directly indicate what operations, such
401+
as HTTP methods for links with "http(s)://" URI schemes, are supported by
402+
the target resource. Instead, operations should be inferred primarily from
403+
link <xref target="rel">relation types</xref> and URI schemes. Additionally,
404+
the presence of keywords related to data use often implies support for certain
405+
operations. Note, however, that a resource may always decline an operation at
406+
runtime, for instance due to application state that controls the operation's
407+
availability.
404408
</t>
405409
<t>
406-
An "href" with at least one template variable and with an "hrefSchema" allows using external
407-
data to resolve the template, and falls back to resolving any remaining variables from the instance.
410+
There are several ways that a client can use data can with a link:
411+
<list>
412+
<t> URI Template variables resolved from server-supplied instance data </t>
413+
<t> URI Template variables resolved from client input</t>
414+
<t> Replacing or modifying the target resource's representation </t>
415+
<t> Submitting data for processing, where the data has no
416+
inherent relation to the target resource's representation</t>
417+
</list>
408418
</t>
409419
<t>
410-
A link with a "submissionSchema" allows submitting external data either as a request body (if "method" is "post"),
411-
or as a URI query string (if "method" is "get"). Such a query string replaces any query string
412-
present after the "href" template is resolved.
420+
In the human-oriented web, these cases are implemented through
421+
a combination of HTML and JavaScript. The relatively rapid evolution
422+
and broad adoption of JavaScript reduced the need to include all
423+
features in HTML itself.
413424
</t>
414425
<t>
415-
See the individual keyword descriptions below for details related to each of these cases.
426+
Since JSON Hyper-Schema addresses all of these cases, and is consumed
427+
primarily by client code rather than human users, its mechanisms do not
428+
exactly match those of HTML. Instead, three schema keywords describe
429+
the different kinds of input. Unless otherwise specified, schema keywords
430+
are ignored when performing operations to which they are not semantically
431+
relevant.
416432
</t>
433+
<section title="Resolving templated URIs">
434+
<t>
435+
URI Template variables in <xref target="href">"href"</xref> resolve from
436+
server-supplied instance data by default.
437+
<xref target="hrefSchema">"hrefSchema"</xref> allows a link to specify
438+
a schema for resolving template variables from client-supplied data.
439+
Regular JSON Schema validation features can be used to require resolution
440+
for client data, forbid it, or allow client data while falling back to
441+
server-supplied instance data if no client data is provided.
442+
</t>
443+
<t>
444+
This offers a superset of traditional HTML GET forms, and a subset of all
445+
possible URI construction that can be performed by JavaScript. To simulate
446+
an HTML GET form, a link can require client input to all query string variables,
447+
and forbid client input for all other template variables.
448+
</t>
449+
</section>
450+
<section title="Manipulating the target resource representation">
451+
<t>
452+
HTML does not directly support target resource representation manipulation
453+
through forms. Instead, JavaScript accomplishes this by intercepting the
454+
form submission and using the appropriate HTTP request with the form data.
455+
In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
456+
supplies a non-authoritative description of the target resource's representation.
457+
A client can use "targetSchema" to structure input, or (if it is absent or
458+
if the client prefers to only use authoritative information), interact with
459+
the target resource to confirm or discover its representation structure.
460+
</t>
461+
</section>
462+
<section title="Submitting data for processing">
463+
<t>
464+
The <xref target="submissionSchema">"submissionSchema"</xref> and
465+
<xref target="submissionEncType">"submissionEncType"</xref> keywords
466+
describe the domain of the processing function implemented by the target resource.
467+
This directly corresponds to HTML "method"="post" forms.
468+
The <xref target="form">"form"</xref>
469+
keyword can be used to enforce strict semantic compatibility with HTML "post"
470+
forms, limiting operations to those that make use of the submission data.
471+
Otherwise, as noted above, the submission schema and encoding are ignored
472+
for operations to which they are not relevant.
473+
</t>
474+
</section>
417475
</section>
418476

419-
<!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure -->
477+
<!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure -->
420478

421479
<section title="href" anchor="href">
422480
<t>
@@ -512,6 +570,10 @@
512570
months for date-time input but using the standard date-time
513571
format for storage.
514572
</t>
573+
<t>
574+
Omitting this keyword has the same behavior as a schema of false,
575+
which forbids all external data input.
576+
</t>
515577
<figure>
516578
<preamble>
517579
For example, this defines a schema for each of the query string
@@ -579,13 +641,13 @@
579641
</figure>
580642
<t>
581643
<cref>
582-
The above example simulates the behavior found in earlier drafts using only "hrefSchema",
583-
which would allow the concurrent use of "submissionSchema" on a "post" link.
644+
The above example simulates the HTML GET form behavior found in earlier drafts
645+
using only "hrefSchema", which is necessary now that "method" has been removed.
584646
</cref>
585647
</t>
586648
</section>
587649

588-
<section title="rel">
650+
<section title="rel" anchor="rel">
589651
<t>
590652
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 <xref target="RFC5988">IANA Link Relation Type Registry established in RFC 5988</xref>, or a normalized URI following the <xref target="RFC3986">URI production of RFC 3986</xref>.
591653
</t>
@@ -863,69 +925,54 @@ GET /foo/
863925
</section>
864926
</section>
865927

866-
<section title="Submission Form Properties">
928+
<section title="Data Submission Properties">
867929
<t>
868-
The following properties also apply to Link Description Objects, and provide functionality analogous to <xref target="W3C.CR-html5-20140731">HTML forms</xref>, by providing a means for making a request with client- or user-selected information.
930+
The following properties also apply to Link Description Objects,
931+
and provide the ability to describe data for submission to the
932+
target resource for processing, independent of manipulating the
933+
target resource's representation.
869934
</t>
870935

871-
<section title="method" anchor="method">
936+
<section title="form" anchor="form">
937+
<t>
938+
The value of this keyword is a boolean.
939+
</t>
872940
<t>
873-
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
941+
Setting this keyword to true indicates that this link has
942+
semantics analogous to
943+
<xref target="W3C.REC-html5-20141028">HTML "method"="post" forms</xref>.
944+
This imposes additional constraints that are not present if
945+
the value of this keyword is false.
874946
</t>
875947
<t>
876-
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.
948+
In particular, if "form" is true, request payloads SHOULD conform
949+
to <xref target="submissionSchema">"submissionSchema"</xref>
950+
and <xref target="submissionEncType">"submissionEncType"</xref>,
951+
and the link MUST NOT be used with operations that are incompatible
952+
with those semantics.
877953
</t>
878954
<t>
879-
If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation.
955+
Note that <xref target="hrefSchema">"hrefSchema"</xref> already offers a superset
956+
of the functionality of HTML GET forms, so there is no explicit
957+
analogue for that aspect of HTML.
880958
</t>
881959
<t>
882-
Values for this property SHOULD be lowercase, and SHOULD be compared case-insensitive. Use of other values not defined here SHOULD be ignored.
960+
Omitting this keyword has the same behavior as a value of false.
883961
</t>
884962
</section>
885963

886964
<section title="submissionEncType" anchor="submissionEncType">
887965
<t>
888-
If present, this property indicates the media type format the client should use to encode a query parameter or send to the server.
889-
If the method is "get", this will indicate how to encode the query-string that is appended to the "href" link target.
890-
If the method is "post", this indicates which media type to send to the server and how to encode it.
891-
892-
<figure>
893-
<preamble>For example, with the following schema:</preamble>
894-
<artwork>
895-
<![CDATA[{
896-
"links": [{
897-
"submissionEncType": "application/x-www-form-urlencoded",
898-
"method": "get",
899-
"href": "/Product/",
900-
"submissionSchema": {
901-
"properties": {
902-
"name": {
903-
"description": "name of the product"
904-
}
905-
}
906-
}
907-
}]
908-
}]]>
909-
</artwork>
910-
<postamble>This indicates that the client can query the server for instances that have a specific name.</postamble>
911-
</figure>
912-
913-
<figure>
914-
<preamble>For example:</preamble>
915-
<artwork>
916-
<![CDATA[
917-
/Product/?name=Slinky
918-
]]>
919-
</artwork>
920-
</figure>
966+
If present, this property indicates which media type to use
967+
when sending data matching the
968+
<xref target="submissionSchema">"submissionSchema"</xref>
969+
to the target resource for processing, and how to encode it.
921970
</t>
922971
<t>
923-
If the method is "post", "application/json" is the default media type.
972+
Omitting this keyword has the same behavior as a value of
973+
"application/json".
924974
</t>
925975
<t>
926-
As noted under <xref target="method">method</xref>, these fields
927-
are not restricted to HTTP URIs.
928-
929976
<figure>
930977
<preamble>
931978
For example, this link indicates that if you want to
@@ -937,7 +984,6 @@ GET /foo/
937984
<![CDATA[{
938985
"links": [{
939986
"submissionEncType": "multipart/alternative; boundary=ab12",
940-
"method": "post",
941987
"rel": "author",
942988
"href": "mailto:[email protected]{?subject}",
943989
"hrefSchema": {
@@ -970,12 +1016,19 @@ GET /foo/
9701016

9711017
<section title="submissionSchema" anchor="submissionSchema">
9721018
<t>
973-
This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" property.
1019+
This property contains a schema which defines the
1020+
acceptable structure of the document being submitted
1021+
for processing by
1022+
according to the "submissionEncType" property.
9741023
</t>
9751024

9761025
<t>
9771026
Note that this does not define the structure for URI template variables. That is handed by <xref target="hrefSchema">"hrefSchema"</xref>. 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.
9781027
</t>
1028+
<t>
1029+
This can be viewed as describing the domain of the processing
1030+
function implemented by the target resource.
1031+
</t>
9791032

9801033
<t>
9811034
This is a separate concept from the <xref target="targetSchema">"targetSchema"</xref> 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/
10611114
<t>Clarified HTTP use with "targetSchema"</t>
10621115
<t>Renamed "schema" to "submissionSchema"</t>
10631116
<t>Renamed "encType" to "submissionEncType"</t>
1117+
<t>Removed "method", add "form" for HTML "post" form semantics</t>
10641118
</list>
10651119
</t>
10661120
<t hangText="draft-wright-json-schema-hyperschema-00">

0 commit comments

Comments
 (0)