Skip to content

Rework the descriptions of using data with links #293

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 3 commits into from
Apr 9, 2017
Merged

Rework the descriptions of using data with links #293

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
95507e9
Rework the descriptions of using data with links.
handrews Mar 31, 2017
323611b
Switch order based on feedback.
handrews Apr 7, 2017
6bf4061
Standardize on "user agent data"
handrews Apr 8, 2017
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
125 changes: 87 additions & 38 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,38 +387,87 @@
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).
</t>

<section title="Links and data">
<section title="Links, operations, and data">
<t>
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
allow for any variance in the link URI, nor does it allow for a request document.
</t>
<t>
An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving
the template variable from the instance, but does not allow resolving it
from external data, nor does it allow a request document.
</t>
<t>
An "href" with at least one template variable and with an "hrefSchema" allows using external
data to resolve the template, and falls back to resolving any remaining variables from the instance.
<cref>
Note that while the current draft does not provide a way to explicity
indicate HTTP method support, some way of providing a non-authoritative
hint may be added in a future draft (see issue #73 in the GitHub repository).
</cref>
</t>
<t>
A link with a "submissionSchema" allows submitting data for processing.
There are several ways that a client can use data can with a link:
<list>
<t> URI Template variables resolved from server-supplied instance data </t>
<t> URI Template variables resolved from user agent data </t>
<t> Replacing or modifying the target resource's representation </t>
<t> Submitting data for processing, where the data has no
inherent relation to the target resource's representation</t>
</list>
The three ways to use client-supplied data are each addressed by a separate
schema keyword within the link description object. Link operations
ignore schemas that are not relevant to their semantics.
</t>
<t>
See the individual keyword descriptions below for details related to each of these cases.
Link Description Objects do not directly indicate what operations, such
as HTTP methods, are supported by the target resource. Instead, operations
should be inferred primarily from link <xref target="rel">relation types</xref>
and URI schemes. Note, however, that a resource may always decline an operation at
runtime, for instance due to application state that controls the operation's
availability.
</t>
<section title="Resolving templated URIs">
<t>
URI Template variables in <xref target="href">"href"</xref> resolve from
server-supplied instance data by default.
<xref target="hrefSchema">"hrefSchema"</xref> allows a link to specify
a schema for resolving template variables from client-supplied data.
Regular JSON Schema validation features can be used to require resolution
from user agent data, forbid it, or allow user agent data while falling back to
server-supplied instance data if no user agent data is provided.
</t>
<t>
The common pattern of resolving a templated path component with
server-supplied instance data while accepting user agent data to build
a query string can be implemented by setting the "hrefSchema" subschemas
for the path template variables to false, while giving the query string
template variables names that do not appear in the instance. This ensures
that the path variables can only be resolved from the instance, and the
query string variables can only be resolved from user agent data.
See the "hrefSchema" section for an example of this approach.
</t>
</section>
<section title="Manipulating the target resource representation">
<t>
In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
supplies a non-authoritative description of the target resource's representation.
A client can use "targetSchema" to structure input for replacing or
modifying the representation. Alternatively, if "targetSchema" is absent
or if the client prefers to only use authoritative information, it can
interact with the target resource to confirm or discover its representation
structure.
</t>
<t>
"targetSchema" is not intended to describe link operation responses,
except when the response semantics indicate that it is a representation
of the target resource. In all cases, the schema indicated by the response
itself is authoritative. See the
<xref target="targetHTTP" /> for guidance
specific to each HTTP method when using "targetSchema" with HTTP URIs.
</t>
</section>
<section title="Submitting data for processing">
<t>
The <xref target="submissionSchema">"submissionSchema"</xref> and
<xref target="submissionEncType">"submissionEncType"</xref> keywords
describe the domain of the processing function implemented by the target resource.
Otherwise, as noted above, the submission schema and encoding are ignored
for operations to which they are not relevant.
</t>
</section>
</section>

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

<section title="href" anchor="href">
<t>
Expand All @@ -442,7 +491,7 @@
<section title="Values for substitution">
<t>
The URI Template is filled out using data from some combination of an external source and the instance.
Where either instance data or external data may be used, this section will refer simply to "data" or to a "value".
Where either instance data or user agent data may be used, this section will refer simply to "data" or to a "value".
When the source is important, it is specified explicitly.

To allow the use of any object property (including the empty string) or array index, the following rules are defined:
Expand All @@ -458,10 +507,10 @@

<t>
If <xref target="hrefSchema">"hrefSchema"</xref> is present and
external input is provided, the input MUST be a valid instance according
user agent data is provided, the data MUST be a valid instance according
to the value of "hrefSchema".
Template variables, after the process listed above, MUST first
be resolved from the external data instance. Any variables left
be resolved from the user agent data instance. Any variables left
unresolved MUST be resolved from the resource instance data.
</t>

Expand All @@ -484,11 +533,11 @@
<section title="Missing values">
<t>
Sometimes, the appropriate values will not be available.
For example, the template might specify the use of object properties, but no such input was provide (or "hrefSchema" is not present), and the instance is an array or a string.
For example, the template might specify the use of object properties, but no such data was provided (or "hrefSchema" is not present), and the instance is an array or a string.
</t>

<t>
If any of the values required for the template are present in neither the user input (if relevant) or the JSON instance, then substitute values MAY be provided from another source (such as default values).
If any of the values required for the template are neither present in the user agent data (if relevant) nor the JSON instance, then substitute values MAY be provided from another source (such as default values).
Otherwise, the link definition SHOULD be considered not to apply to the instance.
</t>
</section>
Expand All @@ -500,17 +549,17 @@
<t>
The value of the "hrefSchema" link description property MUST be
a valid JSON Schema. This schema is used to validate user input
or other external data for filling out the URI Template in
or other user agent data for filling out the URI Template in
<xref target="href">"href"</xref>, as described in that section.
</t>
<t>
Omitting "hrefSchema" or setting the entire schema to "false" prevents
any external data from being accepted.
any user agent data from being accepted.
</t>
<t>
Implementations MUST NOT attempt to validate values resolved from
resource instance data with "hrefSchema". This allows for different
validation rules for user input, such as supporting spelled-out
validation rules for user agent data, such as supporting spelled-out
months for date-time input but using the standard date-time
format for storage.
</t>
Expand Down Expand Up @@ -544,9 +593,9 @@
<figure>
<preamble>
In this example, the schema for "extra" is given as a reference
to keep the external data validation constraints identical to the
to keep the user agent data validation constraints identical to the
instance validation constraints for the corresponding property,
while "id" is given a false schema to prevent external data for
while "id" is given a false schema to prevent user agent data for
that variable.
</preamble>
<artwork>
Expand Down Expand Up @@ -587,7 +636,7 @@
</t>
</section>

<section title="rel">
<section title="rel" anchor="rel">
<t>
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>.
</t>
Expand Down Expand Up @@ -711,7 +760,7 @@ GET /foo/
the schema may or may not describe the response to any particular
request sent to the link. This property is advisory only.
</t>
<section title="&quot;targetSchema&quot; and HTTP">
<section title="&quot;targetSchema&quot; and HTTP" anchor="targetHTTP">
<t>
The relationship between a resource's representation and
HTTP requests and responses is determined by
Expand Down Expand Up @@ -868,7 +917,7 @@ GET /foo/
<section title="submissionEncType" anchor="submissionEncType">
<t>
If present, this property indicates the media type format the
client should use to for the request payload described by
client should use for the request payload described by
<xref target="submissionSchema">"submissionSchema"</xref>.
</t>
<t>
Expand Down Expand Up @@ -935,7 +984,7 @@ GET /foo/
</t>
<t>
Omitting "submissionSchema" or setting the entire schema to "false" prevents
any external data from being accepted.
any user agent data from being accepted.
</t>
</section>
</section>
Expand Down