Skip to content

Commit 95507e9

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 bd227e5 commit 95507e9

File tree

1 file changed

+76
-27
lines changed

1 file changed

+76
-27
lines changed

‎jsonschema-hyperschema.xml

+76-27
Original file line numberDiff line numberDiff line change
@@ -387,38 +387,87 @@
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+
See the "hrefSchema" section for an example of this approach.
438+
</t>
439+
</section>
440+
<section title="Manipulating the target resource representation">
441+
<t>
442+
In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref>
443+
supplies a non-authoritative description of the target resource's representation.
444+
A client can use "targetSchema" to structure input for replacing or
445+
modifying the representation. Alternatively, if "targetSchema" is absent
446+
or if the client prefers to only use authoritative information, it can
447+
interact with the target resource to confirm or discover its representation
448+
structure.
449+
</t>
450+
<t>
451+
"targetSchema" is not intended to describe link operation responses,
452+
except when the response semantics indicate that it is a representation
453+
of the target resource. In all cases, the schema indicated by the response
454+
itself is authoritative. See the
455+
<xref target="targetHTTP" /> for guidance
456+
specific to each HTTP method when using "targetSchema" with HTTP URIs.
457+
</t>
458+
</section>
459+
<section title="Submitting data for processing">
460+
<t>
461+
The <xref target="submissionSchema">"submissionSchema"</xref> and
462+
<xref target="submissionEncType">"submissionEncType"</xref> keywords
463+
describe the domain of the processing function implemented by the target resource.
464+
Otherwise, as noted above, the submission schema and encoding are ignored
465+
for operations to which they are not relevant.
466+
</t>
467+
</section>
419468
</section>
420469

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

423472
<section title="href" anchor="href">
424473
<t>
@@ -587,7 +636,7 @@
587636
</t>
588637
</section>
589638

590-
<section title="rel">
639+
<section title="rel" anchor="rel">
591640
<t>
592641
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>.
593642
</t>
@@ -711,7 +760,7 @@ GET /foo/
711760
the schema may or may not describe the response to any particular
712761
request sent to the link. This property is advisory only.
713762
</t>
714-
<section title="&quot;targetSchema&quot; and HTTP">
763+
<section title="&quot;targetSchema&quot; and HTTP" anchor="targetHTTP">
715764
<t>
716765
The relationship between a resource's representation and
717766
HTTP requests and responses is determined by
@@ -868,7 +917,7 @@ GET /foo/
868917
<section title="submissionEncType" anchor="submissionEncType">
869918
<t>
870919
If present, this property indicates the media type format the
871-
client should use to for the request payload described by
920+
client should use for the request payload described by
872921
<xref target="submissionSchema">"submissionSchema"</xref>.
873922
</t>
874923
<t>

0 commit comments

Comments
 (0)