Skip to content

Guidance on content negotiation #451

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 3 commits into from
Oct 24, 2017
Merged

Guidance on content negotiation #451

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ac746e6
Guidance on content negotiation
handrews Oct 20, 2017
bf580f3
Fix typo
handrews Oct 23, 2017
e1d1290
Discuss connecting instances and hyper-schemas
handrews Oct 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
45 changes: 40 additions & 5 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1297,11 +1297,19 @@ for varname in templateData:
using protocols such as CoAP that are explicitly analogous to HTTP.
</t>
<t>
This section provides guidance on how to define links for use with each
common HTTP method, and how collection resources impose additional constraints
on the use of HTTP POST. Additionally, guidance is provided on hinting at
HTTP response header values and describing possible HTTP request headers
that are relevant to the given resource.
This section provides guidance on how to use each common HTTP method with a link,
and how colletion resources impose additional constraints on HTTP POST.
Additionally, guidance is provided on hinting at HTTP response header values and
describing possible HTTP request headers that are relevant to the given resource.
</t>
<t>
<xref target="json-schema">Section 11 of the JSON Schema core specification</xref>
provides guidance on linking instances in a hypermedia system to their schemas.
This may be done with network-accessible schemas, or may simply identify schemas
which were pre-packaged within the client application. JSON Hyper-Schema
intentionally does not constrain this mechanism, although it is RECOMMENDED that
the techniques outlined in the core specification be used to whatever extent
is possible.
</t>
<section title="One link per target and relation type">
<t>
Expand Down Expand Up @@ -1352,6 +1360,8 @@ for varname in templateData:
that are suitable for PATCH-ing define a syntax for expressing changes
to a document, which can be applied to the representation described by
"targetSchema" to determine the set of syntactically valid request payloads.
Often, the simplest way to validate a PATCH is to apply it and validate
the result as a normal representation.
</t>
<t>
HTTP POST request payloads are described by the "submissionSchema" and
Expand Down Expand Up @@ -1429,6 +1439,31 @@ for varname in templateData:
<xref target="collectionAndItem" />.
</t>
</section>
<section title="Content negotiation and schema evolution">
<t>
JSON Hyper-Schema facilitates HTTP content negotiation, and allows for
a hybrid of the proactive and reactive strategies. As mentioned
above, a hyper-schema can include a schema for HTTP headers such as
"Accept", "Accept-Charset", "Accept-Language", etc with the "headerSchema"
keyword. A user agent or client application can use information in
this schema, such as an enumerated list of supported languages, in lieu of
making an initial request to start the reactive negotiation process.
</t>
<t>
In this way, the proactive content negotiation technique of setting these
headers can be informed by server information about what values are
possible, similar to examining a list of alternatives in reactive negotiation.
</t>
<t>
For media types that allow specifying a schema as a media type parameter,
the "Accept" values sent in a request or advertised in "headerSchema" can
include the URI(s) of the schema(s) to which the negotiated representation
is expected to conform. One possible use for schema parameters in
content negotiation is if the resource has conformed to several different
schema versions over time. The client can indicate what version(s) it
understands in the "Accept" header in this way.
</t>
</section>
</section>

<section title="Examples" anchor="examples">
Expand Down