Skip to content

Commit 82e783b

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 82e783b

File tree

1 file changed

+120
-67
lines changed

1 file changed

+120
-67
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 120 additions & 67 deletions
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,92 @@
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 POST forms. The <xref target="form">"form"</xref>
468+
keyword can be used to enforce strict semantic compatibility with HTML POST
469+
forms, limiting operations to those that make use of the submission data.
470+
Otherwise, as noted above, the submission schema and encoding are ignored
471+
for operations to which they are not relevant.
472+
</t>
473+
</section>
417474
</section>
418475

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

421478
<section title="href" anchor="href">
422479
<t>
@@ -512,6 +569,10 @@
512569
months for date-time input but using the standard date-time
513570
format for storage.
514571
</t>
572+
<t>
573+
Omitting this keyword has the same behavior as a schema of false,
574+
which forbids all external data input.
575+
</t>
515576
<figure>
516577
<preamble>
517578
For example, this defines a schema for each of the query string
@@ -579,13 +640,13 @@
579640
</figure>
580641
<t>
581642
<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.
643+
The above example simulates the HTML GET form behavior found in earlier drafts
644+
using only "hrefSchema", which is necessary now that "method" has been removed.
584645
</cref>
585646
</t>
586647
</section>
587648

588-
<section title="rel">
649+
<section title="rel" anchor="rel">
589650
<t>
590651
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>.
591652
</t>
@@ -863,69 +924,54 @@ GET /foo/
863924
</section>
864925
</section>
865926

866-
<section title="Submission Form Properties">
927+
<section title="Data Submission Properties">
867928
<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.
929+
The following properties also apply to Link Description Objects,
930+
and provide the ability to describe data for submission to the
931+
target resource for processing, independent of manipulating the
932+
target resource's representation.
869933
</t>
870934

871-
<section title="method" anchor="method">
935+
<section title="form" anchor="form">
936+
<t>
937+
The value of this keyword is a boolean.
938+
</t>
872939
<t>
873-
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
940+
Setting this keyword to true indicates that this link has
941+
semantics analogous to
942+
<xref target="W3C.REC-html5-20141028">HTML POST forms</xref>.
943+
This imposes additional constraints that are not present if
944+
the value of this keyword is false.
874945
</t>
875946
<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.
947+
In particular, if "form" is true, request payloads SHOULD conform
948+
to <xref target="submissionSchema">"submissionSchema"</xref>
949+
and <xref target="submissionEncType">"submissionEncType"</xref>,
950+
and the link MUST NOT be used with operations that are incompatible
951+
with those semantics.
877952
</t>
878953
<t>
879-
If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation.
954+
Note that <xref target="hrefSchema">"hrefSchema"</xref> already offers a superset
955+
of the functionality of HTML GET forms, so there is no explicit
956+
analogue for that aspect of HTML.
880957
</t>
881958
<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.
959+
Omitting this keyword has the same behavior as a value of false.
883960
</t>
884961
</section>
885962

886963
<section title="submissionEncType" anchor="submissionEncType">
887964
<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>
965+
If present, this property indicates which media type to use
966+
when sending data matching the
967+
<xref target="submissionSchema">"submissionSchema"</xref>
968+
to the target resource for processing, and how to encode it.
921969
</t>
922970
<t>
923-
If the method is "post", "application/json" is the default media type.
971+
Omitting this keyword has the same behavior as a value of
972+
"application/json".
924973
</t>
925974
<t>
926-
As noted under <xref target="method">method</xref>, these fields
927-
are not restricted to HTTP URIs.
928-
929975
<figure>
930976
<preamble>
931977
For example, this link indicates that if you want to
@@ -937,7 +983,6 @@ GET /foo/
937983
<![CDATA[{
938984
"links": [{
939985
"submissionEncType": "multipart/alternative; boundary=ab12",
940-
"method": "post",
941986
"rel": "author",
942987
"href": "mailto:[email protected]{?subject}",
943988
"hrefSchema": {
@@ -970,12 +1015,19 @@ GET /foo/
9701015

9711016
<section title="submissionSchema" anchor="submissionSchema">
9721017
<t>
973-
This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" property.
1018+
This property contains a schema which defines the
1019+
acceptable structure of the document being submitted
1020+
for processing by
1021+
according to the "submissionEncType" property.
9741022
</t>
9751023

9761024
<t>
9771025
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.
9781026
</t>
1027+
<t>
1028+
This can be viewed as describing the domain of the processing
1029+
function implemented by the target resource.
1030+
</t>
9791031

9801032
<t>
9811033
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 +1113,7 @@ GET /foo/
10611113
<t>Clarified HTTP use with "targetSchema"</t>
10621114
<t>Renamed "schema" to "submissionSchema"</t>
10631115
<t>Renamed "encType" to "submissionEncType"</t>
1116+
<t>Removed "method", add "form" for HTML POST form semantics</t>
10641117
</list>
10651118
</t>
10661119
<t hangText="draft-wright-json-schema-hyperschema-00">

0 commit comments

Comments
 (0)