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 1 commit
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
103 changes: 76 additions & 27 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.
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.
Copy link
Member

Choose a reason for hiding this comment

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

It seems like we're comparing the LDO against something (HTML forms?), but there's no indication of what that is.

I would move this paragraph down one so we lead with what it does, not with what it doesn't do.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good point, fixed.

</t>
<t>
See the individual keyword descriptions below for details related to each of these cases.
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 client data </t>
Copy link
Member

@awwright awwright Apr 7, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

These two lines might be too easy to conflate. I would say something like

  • Plain links, where all variables in the URI Template (if any) are filled from instance data
  • Link templates, where the URI Template contains variables that can be filled in by a users or agent

Copy link
Contributor Author

@handrews handrews Apr 7, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

Your phrasing is not clear to me, and I don't have any intuition for "Plain links" vs "Link templates", especially because your plain links obviously involve template variables.

The distinction is not across the template, it's that there are different ways to use template variables, which might appear in any combination in a template.

Copy link
Member

Choose a reason for hiding this comment

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

Oh I see. I suppose that works.

What about "URI Template variables resolved from user input"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

What about "URI Template variables resolved from user input"?

This is a good point: I've avoided "user input" in favor of "client data" because of situations (like autonomous Things in the Internet of Things sense) where there is no direct user input, but there is data coming through the client from somewhere.

So I don't want to make it sound like there has to be an actual user interaction involved, but I do want the purpose to be clear.

client input? user-agent input?

<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>
<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 client data, forbid it, or allow client data while falling back to
server-supplied instance data if no client data is provided.
</t>
<t>
The common pattern of resolving a templated path component with
server-supplied instance data while accepting client 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 client 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 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