Skip to content

Commit 039d296

Browse files
handrewshandrews
committed
Remove "method" and analogies to HTML forms.
The feedback to draft-wright-json-schema-hyperschema-00 and from the final review for draft-wright-json-schema-hyperschema-01 has made it clear that "method" is extremely confusing, and no two people can agree on the correct usage. The only clear impulse is to use the draft-luff-json-hyper-schema-00 meaning (explicit specification of HTTP methods), which is not the desired approach. "method" is not actually necessary now that "hrefSchema" and "submissionSchema" have separated the roles that were previously both implemented by "schema" depending on the value of "method". Therefore remove it to prevent incorrect assumptions about its behavior and gather feedback on what behavior is truly needed. With "method" gone, it makes sense to remove the references to HTML forms as the analogy is no longer direct. However, there are still open issues around both whether and how to explicitly indicate HTML form vs anchor semantics, and whether and how to allow directly specifying HTTP methods (as was allowed by draft-luff-json-hyper-schema-00). Since there are no longer citations of HTML, that reference has been removed. If a new keyword is added for HTML form semantics, then it will be restored as needed.
1 parent 2e4f18c commit 039d296

File tree

1 file changed

+50
-96
lines changed

1 file changed

+50
-96
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 50 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@
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">
1413
]>
1514
<?rfc toc="yes"?>
1615
<?rfc symrefs="yes"?>
@@ -390,8 +389,13 @@
390389

391390
<section title="Links and data">
392391
<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>.
392+
"Form"-like functionality can be defined by use of the
393+
<xref target="submissionSchema">"submissionSchema"</xref> and
394+
<xref target="submissionEncType">"submissionEncType"</xref> keywords,
395+
which supply a description of data to sent to the target resource for processing.
396+
Functionality equivalent to dynamic URI generation is available through
397+
the <xref target="href">"href"</xref> template and
398+
<xref target="hrefSchema">"hrefSchema"</xref>.
395399
</t>
396400
<t>
397401
The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not
@@ -407,9 +411,7 @@
407411
data to resolve the template, and falls back to resolving any remaining variables from the instance.
408412
</t>
409413
<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.
414+
A link with a "submissionSchema" allows submitting data for processing.
413415
</t>
414416
<t>
415417
See the individual keyword descriptions below for details related to each of these cases.
@@ -579,8 +581,8 @@
579581
</figure>
580582
<t>
581583
<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.
584+
The above example simulates the behavior handled in earlier drafts
585+
with a "method" of "get" by using the new "hrefSchema" keyword,
584586
</cref>
585587
</t>
586588
</section>
@@ -863,81 +865,30 @@ GET /foo/
863865
</section>
864866
</section>
865867

866-
<section title="Submission Form Properties">
868+
<section title="submissionEncType" anchor="submissionEncType">
867869
<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.
870+
If present, this property indicates the media type format the
871+
client should use to for the request payload described by
872+
<xref target="submissionSchema">"submissionSchema"</xref>.
869873
</t>
874+
<t>
875+
Omitting this keyword has the same behavior as a value of application/json.
876+
</t>
877+
<t>
878+
Note that "submissionEncType" and "submissionSchema"
879+
are not restricted to HTTP URIs.
870880

871-
<section title="method" anchor="method">
872-
<t>
873-
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
874-
</t>
875-
<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.
877-
</t>
878-
<t>
879-
If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation.
880-
</t>
881-
<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.
883-
</t>
884-
</section>
885-
886-
<section title="submissionEncType" anchor="submissionEncType">
887-
<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>
921-
</t>
922-
<t>
923-
If the method is "post", "application/json" is the default media type.
924-
</t>
925-
<t>
926-
As noted under <xref target="method">method</xref>, these fields
927-
are not restricted to HTTP URIs.
928-
929-
<figure>
930-
<preamble>
931-
For example, this link indicates that if you want to
932-
send an email to the author of the context resource,
933-
your client needs to ask for both a plain text
934-
and an HTML representation.
935-
</preamble>
936-
<artwork>
881+
<figure>
882+
<preamble>
883+
For example, this link indicates that if you want to
884+
send an email to the author of the context resource,
885+
your client needs to ask for both a plain text
886+
and an HTML representation.
887+
</preamble>
888+
<artwork>
937889
<![CDATA[{
938890
"links": [{
939891
"submissionEncType": "multipart/alternative; boundary=ab12",
940-
"method": "post",
941892
"rel": "author",
942893
"href": "mailto:[email protected]{?subject}",
943894
"hrefSchema": {
@@ -963,26 +914,29 @@ GET /foo/
963914
}
964915
}]
965916
}]]>
966-
</artwork>
967-
</figure>
968-
</t>
969-
</section>
970-
971-
<section title="submissionSchema" anchor="submissionSchema">
972-
<t>
973-
This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" property.
974-
</t>
917+
</artwork>
918+
</figure>
919+
</t>
920+
</section>
975921

976-
<t>
977-
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.
978-
</t>
922+
<section title="submissionSchema" anchor="submissionSchema">
923+
<t>
924+
This property contains a schema which defines the acceptable structure
925+
of the document to be encoded according to the "submissionEncType" property
926+
and sent to the target resource for processing. This can be viewed as
927+
describing the domain of the processing function implemented by the
928+
target resource.
929+
</t>
979930

980-
<t>
981-
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.
982-
"submissionSchema" is intended for use with requests that have payloads that are not
983-
defined in terms of the target representation.
984-
</t>
985-
</section>
931+
<t>
932+
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.
933+
"submissionSchema" is intended for use with requests that have payloads that are not
934+
defined in terms of the target representation.
935+
</t>
936+
<t>
937+
Omitting "submissionSchema" or setting the entire schema to "false" prevents
938+
any external data from being accepted.
939+
</t>
986940
</section>
987941
</section>
988942

@@ -1018,7 +972,6 @@ GET /foo/
1018972
&rfc5789;
1019973
&rfc5988;
1020974
&rfc7231;
1021-
&html5;
1022975
</references>
1023976

1024977
<section title="Acknowledgments">
@@ -1061,6 +1014,7 @@ GET /foo/
10611014
<t>Clarified HTTP use with "targetSchema"</t>
10621015
<t>Renamed "schema" to "submissionSchema"</t>
10631016
<t>Renamed "encType" to "submissionEncType"</t>
1017+
<t>Removed "method"</t>
10641018
</list>
10651019
</t>
10661020
<t hangText="draft-wright-json-schema-hyperschema-00">

0 commit comments

Comments
 (0)