Skip to content
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

Clarify various usage scenarios for URI templates #387

Merged
merged 1 commit into from
Sep 7, 2017
Merged

Clarify various usage scenarios for URI templates #387

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 32 additions & 7 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -504,15 +504,40 @@
to server-supplied instance data if no user agent data is provided.
</t>
<t>
The common pattern of resolving a templated path component with
server-supplied instance data while accepting user agent 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 user agent data.
To implement the common pattern of resolving a templated path component
with server-supplied instance data while accepting user agent data to build
a query string:
<list style="symbols">
<t>
set the "hrefSchema" subschemas for the path template variables
to false, to disallow user agent input
</t>
<t>
give the query string template variables names that do not appear
in the instance, to prevent resolving them from the instance
</t>
</list>
See the "hrefSchema" section for an example of this approach.
</t>
<t>
To implement the equivalent of an input form pre-populated with
pre-existing instance data:
<list style="symbols">
<t>
ensure that each variable in the form resolves from the appropriate
field in the instance, which provides the initial value that will
continue to be used if the user agent takes no action to change it
</t>
<t> provide a validation schema for each of those fields in
"hrefSchema", to describe what user agent input may be allowed
to replace it
</t>
</list>
This can be done with variables in any component of the URI template
(path, query string, etc.) While the word "form" is used here,
JSON Hyper-Schema does not constraint the nature of this interaction, which
may or may not involve rendering an interactive form.
</t>
</section>
<section title="Manipulating the target resource representation">
<t>
Expand Down