Skip to content

Commit e4f3667

Browse files
handrewshandrews
committed
Add a section on links and data.
1 parent 3f9ca46 commit e4f3667

File tree

1 file changed

+50
-17
lines changed

1 file changed

+50
-17
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 50 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -366,9 +366,33 @@
366366
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).
367367
</t>
368368

369-
<t>
370-
"Form"-like functionality can be defined by use of the "method" and "schema" keywords, which supplies a schema describing the data to supply to the server.
371-
</t>
369+
<section title="Links and data">
370+
<t>
371+
"Form"-like functionality can be defined by use of the <xref target="method">"method"</xref> and <xref target="schema">"schema"</xref> keywords, which supplies a schema describing the data to supply to the server.
372+
Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>.
373+
</t>
374+
<t>
375+
The simplest kind of link has an "href" with no template variables, and no "schema". This does not
376+
allow for any variance in the link URI, nor does it allow for a request document.
377+
</t>
378+
<t>
379+
An "href" with at least one template variable, but no "hrefSchema" or "schema", allows resolving
380+
the template variable from the instance, but does not allow resolving it
381+
from external data, nor does it allow a request document.
382+
</t>
383+
<t>
384+
An "href" with at least one template variable and with an "hrefSchema" allows using external
385+
data to resolve the template, and falls back to resolving any remaining variables from the instance.
386+
</t>
387+
<t>
388+
A link with a "schema" allows submitting external data either as a request body (if "method" is "post"),
389+
or as a URI query string (if "method" is "get"). Such a query string replaces any query string
390+
present after the "href" template is resolved.
391+
</t>
392+
<t>
393+
See the individual keyword descriptions below for details related to each of these cases.
394+
</t>
395+
</section>
372396

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

@@ -473,27 +497,30 @@
473497

474498
<section title="Values for substitution">
475499
<t>
476-
After pre-processing, the URI Template is filled out using data from some combination of user input and the instance.
500+
After pre-processing, the URI Template is filled out using data from some combination of an externa source and the instance.
501+
Where either instance data or external data may be used, this section will refer simply to "data" or to a "value".
502+
When the source is important, it is specified explicitly.
477503

478504
To allow the use of any object property (including the empty string), array index, or the instance value itself, the following rules are defined:
479505
</t>
480506

481507
<t>
482508
For a given variable name in the URI Template, the value to use is determined as follows:
483509
<list>
484-
<t>If the variable name is "%73elf", then the instance value itself MUST be used.</t>
485-
<t>If the variable name is "%65mpty", then the instances's empty-string ("") property MUST be used (if it exists).</t>
486-
<t>If the instance is an array, and the variable name is a representation of a non-negative integer, then the value at the corresponding array index MUST be used (if it exists).</t>
510+
<t>If the variable name is "%73elf", then the value itself MUST be used.</t>
511+
<t>If the variable name is "%65mpty", then the empty-string ("") property MUST be used (if it exists).</t>
512+
<t>If the data is an array, and the variable name is a representation of a non-negative integer, then the value at the corresponding array index MUST be used (if it exists).</t>
487513
<t>Otherwise, the variable name should be percent-decoded, and the corresponding object property MUST be used (if it exists).</t>
488514
</list>
489515
</t>
490516

491517
<t>
492518
If <xref target="hrefSchema">"hrefSchema"</xref> is present and
493-
user input is provided, the input MUST be valid according to the value of "hrefSchema".
519+
external input is provided, the input MUST be a valid instance according
520+
to the value of "hrefSchema".
494521
Template variables, after the process listed above, MUST first
495-
be resolved from the user input instance. Any variables left
496-
unresolved MUST be resolved from the resource instance.
522+
be resolved from the external data instance. Any variables left
523+
unresolved MUST be resolved from the resource instance data.
497524
</t>
498525

499526
<section title="Converting to strings">
@@ -531,16 +558,16 @@
531558
<t>
532559
The value of the "hrefSchema" link description property MUST be
533560
a valid JSON Schema. This schema is used to validate user input
534-
for filling out the URI Template in
561+
or other external data for filling out the URI Template in
535562
<xref target="href">"href"</xref>, as described in that section.
536563
</t>
537564
<t>
538565
Omitting "hrefSchema" or setting the entire schema to "false" prevents
539-
any user input from being accepted.
566+
any external data from being accepted.
540567
</t>
541568
<t>
542569
Implementations MUST NOT attempt to validate values resolved from
543-
instance data with "hrefSchema". This allows for different
570+
resource instance data with "hrefSchema". This allows for different
544571
validation rules for user input, such as supporting spelled-out
545572
months for date-time input but using the standard date-time
546573
format for storage.
@@ -575,9 +602,9 @@
575602
<figure>
576603
<preamble>
577604
In this example, the schema for "extra" is given as a reference
578-
to keep the user input validation constraints identical to the
605+
to keep the external data validation constraints identical to the
579606
instance validation constraints for the corresponding property,
580-
while "id" is given a false schema to prevent user input for
607+
while "id" is given a false schema to prevent external data for
581608
that variable.
582609
</preamble>
583610
<artwork>
@@ -610,6 +637,12 @@
610637
}]]>
611638
</artwork>
612639
</figure>
640+
<t>
641+
<cref>
642+
The above example simulates the behavior found in earlier drafts using only "hrefSchema",
643+
which would allow the concurrent use of "schema" on a "post" link.
644+
</cref>
645+
</t>
613646
</section>
614647

615648
<section title="rel">
@@ -878,7 +911,7 @@ GET /foo/
878911
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.
879912
</t>
880913

881-
<section title="method">
914+
<section title="method" anchor="method">
882915
<t>
883916
This property specifies that the client can construct a templated query or non-idempotent request to a resource.
884917
</t>
@@ -933,7 +966,7 @@ GET /foo/
933966
</t>
934967
</section>
935968

936-
<section title="schema">
969+
<section title="schema" anchor="schema">
937970
<t>
938971
This property contains a schema which defines the acceptable structure of the document being encoded according to the "encType" property.
939972
</t>

0 commit comments

Comments
 (0)