Skip to content

Commit b2760eb

Browse files
authored
Merge pull request #387 from handrews/scenarios
Clarify various usage scenarios for URI templates
2 parents 0b897c7 + a6af1ff commit b2760eb

File tree

1 file changed

+32
-7
lines changed

1 file changed

+32
-7
lines changed

jsonschema-hyperschema.xml

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -504,15 +504,40 @@
504504
to server-supplied instance data if no user agent data is provided.
505505
</t>
506506
<t>
507-
The common pattern of resolving a templated path component with
508-
server-supplied instance data while accepting user agent data to build
509-
a query string can be implemented by setting the "hrefSchema" subschemas
510-
for the path template variables to false, while giving the query string
511-
template variables names that do not appear in the instance. This ensures
512-
that the path variables can only be resolved from the instance, and the
513-
query string variables can only be resolved from user agent data.
507+
To implement the common pattern of resolving a templated path component
508+
with server-supplied instance data while accepting user agent data to build
509+
a query string:
510+
<list style="symbols">
511+
<t>
512+
set the "hrefSchema" subschemas for the path template variables
513+
to false, to disallow user agent input
514+
</t>
515+
<t>
516+
give the query string template variables names that do not appear
517+
in the instance, to prevent resolving them from the instance
518+
</t>
519+
</list>
514520
See the "hrefSchema" section for an example of this approach.
515521
</t>
522+
<t>
523+
To implement the equivalent of an input form pre-populated with
524+
pre-existing instance data:
525+
<list style="symbols">
526+
<t>
527+
ensure that each variable in the form resolves from the appropriate
528+
field in the instance, which provides the initial value that will
529+
continue to be used if the user agent takes no action to change it
530+
</t>
531+
<t> provide a validation schema for each of those fields in
532+
"hrefSchema", to describe what user agent input may be allowed
533+
to replace it
534+
</t>
535+
</list>
536+
This can be done with variables in any component of the URI template
537+
(path, query string, etc.) While the word "form" is used here,
538+
JSON Hyper-Schema does not constraint the nature of this interaction, which
539+
may or may not involve rendering an interactive form.
540+
</t>
516541
</section>
517542
<section title="Manipulating the target resource representation">
518543
<t>

0 commit comments

Comments
 (0)