Skip to content

Add back examples in "JSON Hyper-Schema and HTTP" section #467

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

Closed
wants to merge 2 commits into from
Closed

Add back examples in "JSON Hyper-Schema and HTTP" section #467

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
99712a2
Add back the example in Optimizing HTTP discoverability with "targetH…
dlax Nov 1, 2017
3ce0ca1
Add back examples in Advertising HTTP features with "headerSchema"
dlax Nov 1, 2017
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
86 changes: 86 additions & 0 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
<!ENTITY rfc6901 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6901.xml">
<!ENTITY rfc7230 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7230.xml">
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
<!ENTITY rfc7240 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7240.xml">
<!ENTITY rfc7807 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7807.xml">
<!ENTITY rfc8288 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8288.xml">
<!ENTITY I-D.luff-relative-json-pointer SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-luff-relative-json-pointer-00.xml">
Expand Down Expand Up @@ -1394,6 +1395,21 @@ for varname in templateData:
In general, headers that are likely to have different values at different
times SHOULD NOT be included in "targetHints".
</t>
<figure>
<preamble>
This examples shows several hints that are useful for clients
when determining what requests to make and how to make them.
</preamble>
<artwork>
<![CDATA[{
"targetHints": {
"allow": ["GET", "PUT"],
"accept-patch": ["application/merge-patch+json"],
"accept-ranges": ["none"]
}
}]]>
</artwork>
</figure>
</section>
<section title='Advertising HTTP features with "headerSchema"'>
<t>
Expand All @@ -1420,6 +1436,75 @@ for varname in templateData:
information needed to use conditional requests, the runtime handling of
such headers and related responses is not resource-specific.
</t>
<figure>
<preamble>
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
is a good candidate for description in "headerSchema". It defines
several standard values and allows for extension values.
This schema indicates that the target understands the
"respond-async" preference, the "wait" preference which
takes a number of seconds to wait, as well as "minimal" and
"representation" for the "return" preference.
</preamble>
<artwork>
<![CDATA[{
"headerSchema": {
"type": "object",
"properties": {
"prefer": {
"type": "array",
"items": {
"oneOf": [
{"const": "respond-async"},
{
"type": "object",
"minProperties": 1,
"maxProperties": 1,
"properties": {
{
"return": {
"enum": [
"representation",
"minimal"
]
},
"wait": {
"type": "integer",
"minimum": 1
}
}
}
}
]
},
"uniqueItems": true
}
}
}
}]]>
</artwork>
<postamble>
Each name/value preference pair is a single value of the
header, so each object in the list can only have one such
pair. Simplifying the "response-async" value to a single string
is based on the "Accept-Encoding" example in
<xref target="I-D.reschke-http-jfv">appendix A.4 of the JSON encoding draft</xref>.
</postamble>
</figure>
<t>
The Prefer header also stretches the limits of existing recommendations
for serializing HTTP headers in JSON. It is possible for both the
single string and name/value pair preferences to take additional
name/value parameters. While a single-string preference can accomodate
such parameters following the "Accept-Encoding" example, there is
no example to date of a name/value pair with parameters.
<cref>
We hope to get feedback from hyper-schema authors on what
practical concerns arise, and from there decide how best to
handle them. The specification for this keyword is expected to
become more well-defined in future drafts.
</cref>
</t>
</section>
<section title="Creating resources through collections">
<t>
Expand Down Expand Up @@ -2331,6 +2416,7 @@ Link: <https://api.example.com/trees/1/nodes/456> rev=up
&rfc6573;
&rfc7230;
&rfc7231;
&rfc7240;
&rfc7807;
&rfc8288;
</references>
Expand Down