Skip to content

Guidance on HTTP headers an "targetHints"/"headerSchema" #422

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

Merged
merged 2 commits into from
Oct 8, 2017
Merged

Guidance on HTTP headers an "targetHints"/"headerSchema" #422

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a333e40
Provide guidance on HTTP targetHints
handrews Sep 23, 2017
a6085fe
More guidance on HTTP and headerSchema
handrews Sep 23, 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
34 changes: 31 additions & 3 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1183,6 +1183,19 @@ GET /foo/
Approaches shown in that document's examples SHOULD be applied to other
similarly structured headers wherever possible.
</t>
<t>
It is RECOMMENDED that schema authors provide hints for the values of
the following types of HTTP headers whenever applicable:
<list style="symbols">
<t>Method allowance</t>
<t>Method-specific request media types</t>
<t>Authentication challenges</t>
</list>
</t>
<t>
In general, headers that are likely to have different values at different
times SHOULD NOT be included in "targetHints".
</t>
<t>
No distinction is made between headers that may appear in responses to
different methods, such as HEAD vs OPTIONS.
Expand Down Expand Up @@ -1365,12 +1378,27 @@ GET /foo/
other similarly structured headers wherever possible.
</t>
<t>
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.
It is RECOMMENDED that schema authors describe the available usage of
the following types of HTTP headers whenever applicable:
<list style="symbols">
<t>Content negotiation</t>
<t>Authentication and authorization</t>
<t>Range requests</t>
<t>The "Prefer" header</t>
</list>
</t>
<t>
Headers such as cache control and conditional request headers are generally
implemented by intermediaries rather than the resource, and are therefore
not generally useful to describe. While the resource must supply the
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
Expand Down