Skip to content

Remove "method" and analogies to HTML forms. #292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 4, 2017
Merged

Remove "method" and analogies to HTML forms. #292

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 50 additions & 96 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!ENTITY html5 SYSTEM "http://xml.resource.org/public/rfc/bibxml4/reference.W3C.CR-html5-20140731.xml">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
Expand Down Expand Up @@ -390,8 +389,13 @@

<section title="Links and data">
<t>
"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.
Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>.
Data input functionality can be defined by use of the
<xref target="submissionSchema">"submissionSchema"</xref> and
<xref target="submissionEncType">"submissionEncType"</xref> 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 <xref target="href">"href"</xref> template and
<xref target="hrefSchema">"hrefSchema"</xref>.
</t>
<t>
The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not
Expand All @@ -407,9 +411,7 @@
data to resolve the template, and falls back to resolving any remaining variables from the instance.
</t>
<t>
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.
</t>
<t>
See the individual keyword descriptions below for details related to each of these cases.
Expand Down Expand Up @@ -579,8 +581,8 @@
</figure>
<t>
<cref>
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.
</cref>
</t>
</section>
Expand Down Expand Up @@ -863,81 +865,30 @@ GET /foo/
</section>
</section>

<section title="Submission Form Properties">
<section title="submissionEncType" anchor="submissionEncType">
<t>
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mixed feelings about removing references to the biggest hypermedia format, but eh. Maybe it's for the greater good.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@awwright Understandable, but yeah, I think it will provoke very useful feedback/discussions, and with #288 and #294 we're definitely not closing the discussion. Getting some distance from the way we've been referencing HTML will help us figure out what the right way (if any) really is. I think it's just been kind of on autopilot for a lot of people (not @jdesrosiers who has obviously put a lot of thought into it, but a lot of people who are not really questioning how the spec works as much).

If present, this property indicates the media type format the
client should use to for the request payload described by
<xref target="submissionSchema">"submissionSchema"</xref>.
</t>
<t>
Omitting this keyword has the same behavior as a value of application/json.
</t>
<t>
Note that "submissionEncType" and "submissionSchema"
are not restricted to HTTP URIs.

<section title="method" anchor="method">
<t>
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
</t>
<t>
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.
</t>
<t>
If "method" is "post", the link specifies how a user can construct a document to submit to the link target for evaluation.
</t>
<t>
Values for this property SHOULD be lowercase, and SHOULD be compared case-insensitive. Use of other values not defined here SHOULD be ignored.
</t>
</section>

<section title="submissionEncType" anchor="submissionEncType">
<t>
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.

<figure>
<preamble>For example, with the following schema:</preamble>
<artwork>
<![CDATA[{
"links": [{
"submissionEncType": "application/x-www-form-urlencoded",
"method": "get",
"href": "/Product/",
"submissionSchema": {
"properties": {
"name": {
"description": "name of the product"
}
}
}
}]
}]]>
</artwork>
<postamble>This indicates that the client can query the server for instances that have a specific name.</postamble>
</figure>

<figure>
<preamble>For example:</preamble>
<artwork>
<![CDATA[
/Product/?name=Slinky
]]>
</artwork>
</figure>
</t>
<t>
If the method is "post", "application/json" is the default media type.
</t>
<t>
As noted under <xref target="method">method</xref>, these fields
are not restricted to HTTP URIs.

<figure>
<preamble>
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.
</preamble>
<artwork>
<figure>
<preamble>
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.
</preamble>
<artwork>
<![CDATA[{
"links": [{
"submissionEncType": "multipart/alternative; boundary=ab12",
"method": "post",
"rel": "author",
"href": "mailto:[email protected]{?subject}",
"hrefSchema": {
Expand All @@ -963,26 +914,29 @@ GET /foo/
}
}]
}]]>
</artwork>
</figure>
</t>
</section>

<section title="submissionSchema" anchor="submissionSchema">
<t>
This property contains a schema which defines the acceptable structure of the document being encoded according to the "submissionEncType" property.
</t>
</artwork>
</figure>
</t>
</section>

<t>
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.
</t>
<section title="submissionSchema" anchor="submissionSchema">
<t>
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.
</t>

<t>
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.
"submissionSchema" is intended for use with requests that have payloads that are not
defined in terms of the target representation.
</t>
</section>
<t>
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.
"submissionSchema" is intended for use with requests that have payloads that are not
defined in terms of the target representation.
</t>
<t>
Omitting "submissionSchema" or setting the entire schema to "false" prevents
any external data from being accepted.
</t>
</section>
</section>

Expand Down Expand Up @@ -1018,7 +972,6 @@ GET /foo/
&rfc5789;
&rfc5988;
&rfc7231;
&html5;
</references>

<section title="Acknowledgments">
Expand Down Expand Up @@ -1061,6 +1014,7 @@ GET /foo/
<t>Clarified HTTP use with "targetSchema"</t>
<t>Renamed "schema" to "submissionSchema"</t>
<t>Renamed "encType" to "submissionEncType"</t>
<t>Removed "method"</t>
</list>
</t>
<t hangText="draft-wright-json-schema-hyperschema-00">
Expand Down