diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 8935e9e2..4d7b4935 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -1297,11 +1297,19 @@ for varname in templateData:
using protocols such as CoAP that are explicitly analogous to HTTP.
- 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.
+
+
+ Section 11 of the JSON Schema core specification
+ 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.
@@ -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.
HTTP POST request payloads are described by the "submissionSchema" and
@@ -1429,6 +1439,31 @@ for varname in templateData:
.
+
+
+ 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.
+
+
+ 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.
+
+
+ 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.
+
+