Skip to content

Commit 22389d4

Browse files
handrewshandrews
committed
Rework the descriptions of using data with links.
This replaces the rather lengthy discussion of hrefSchema with a more concise and complete description of all of the ways to use data with links. This should now serve to set the context for the various ways to use LDOs.
1 parent 9864abb commit 22389d4

File tree

1 file changed

+71
-25
lines changed

1 file changed

+71
-25
lines changed

‎jsonschema-hyperschema.xml

+71-25
Original file line numberDiff line numberDiff line change
@@ -387,35 +387,81 @@
387387
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).
388388
</t>
389389

390-
<section title="Links and data">
390+
<section title="Links, operations, and data">
391391
<t>
392-
Data input 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 send 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>.
399-
</t>
400-
<t>
401-
The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not
402-
allow for any variance in the link URI, nor does it allow for a request document.
403-
</t>
404-
<t>
405-
An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving
406-
the template variable from the instance, but does not allow resolving it
407-
from external data, nor does it allow a request document.
408-
</t>
409-
<t>
410-
An "href" with at least one template variable and with an "hrefSchema" allows using external
411-
data to resolve the template, and falls back to resolving any remaining variables from the instance.
392+
<cref>
393+
Note that while the current draft does not provide a way to explicity
394+
indicate HTTP method support, some way of providing a non-authoritative
395+
hint may be added in a future draft (see issue #73 in the GitHub repository).
396+
</cref>
412397
</t>
413398
<t>
414-
A link with a "submissionSchema" allows submitting data for processing.
399+
Link Description Objects do not directly indicate what operations, such
400+
as HTTP methods, are supported by the target resource. Instead, operations
401+
should be inferred primarily from link <xref target="rel">relation types</xref>
402+
and URI schemes. Note, however, that a resource may always decline an operation at
403+
runtime, for instance due to application state that controls the operation's
404+
availability.
415405
</t>
416406
<t>
417-
See the individual keyword descriptions below for details related to each of these cases.
407+
There are several ways that a client can use data can with a link:
408+
<list>
409+
<t> URI Template variables resolved from server-supplied instance data </t>
410+
<t> URI Template variables resolved from client data </t>
411+
<t> Replacing or modifying the target resource's representation </t>
412+
<t> Submitting data for processing, where the data has no
413+
inherent relation to the target resource's representation</t>
414+
</list>
415+
The three ways to use client-supplied data are each addressed by a separate
416+
schema keyword within the link description object. Link operations
417+
ignore schemas that are not relevant to their semantics.
418418
</t>
419+
<section title="Resolving templated URIs">
420+
<t>
421+
URI Template variables in <xref target="href">"href"</xref> resolve from
422+
server-supplied instance data by default.
423+
<xref target="hrefSchema">"hrefSchema"</xref> allows a link to specify
424+
a schema for resolving template variables from client-supplied data.
425+
Regular JSON Schema validation features can be used to require resolution
426+
from client data, forbid it, or allow client data while falling back to
427+
server-supplied instance data if no client data is provided.
428+
</t>
429+
<t>
430+
The common pattern of resolving a templated path component with
431+
server-supplied instance data while accepting client data to build
432+
a query string can be implemented by setting the "hrefSchema" subschemas
433+
for the path template variables to false, while giving the query string
434+
template variables names that do not appear in the instance. This ensures
435+
that the path variables can only be resolved from the instance, and the
436+
query string variables can only be resolved from client data.
437+
</t>
438+
</section>
439+
<section title="Manipulating the target resource representation">
440+
<t>
441+
In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
442+
supplies a non-authoritative description of the target resource's representation.
443+
A client can use "targetSchema" to structure input for replacing or
444+
modifying the representation. Alternatively, if "targetSchema" is absent
445+
or if the client prefers to only use authoritative information, it can
446+
interact with the target resource to confirm or discover its representation
447+
structure.
448+
</t>
449+
<t>
450+
"targetSchema" is not intended to describe link operation responses,
451+
except when the response semantics indicate that it is a representation
452+
of the target resource. In all cases, the schema indicated by the response
453+
itself is authoritative.
454+
</t>
455+
</section>
456+
<section title="Submitting data for processing">
457+
<t>
458+
The <xref target="submissionSchema">"submissionSchema"</xref> and
459+
<xref target="submissionEncType">"submissionEncType"</xref> keywords
460+
describe the domain of the processing function implemented by the target resource.
461+
Otherwise, as noted above, the submission schema and encoding are ignored
462+
for operations to which they are not relevant.
463+
</t>
464+
</section>
419465
</section>
420466

421467
<!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure -->
@@ -587,7 +633,7 @@
587633
</t>
588634
</section>
589635

590-
<section title="rel">
636+
<section title="rel" anchor="rel">
591637
<t>
592638
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>.
593639
</t>
@@ -868,7 +914,7 @@ GET /foo/
868914
<section title="submissionEncType" anchor="submissionEncType">
869915
<t>
870916
If present, this property indicates the media type format the
871-
client should use to for the request payload described by
917+
client should use for the request payload described by
872918
<xref target="submissionSchema">"submissionSchema"</xref>.
873919
</t>
874920
<t>

0 commit comments

Comments
 (0)