diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 3e0cfcf4..5f5f2a0b 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -10,6 +10,7 @@
+
]>
@@ -1028,6 +1029,84 @@ GET /foo/
+
+
+
+ This section attempts to strike a balance between comprehensiveness
+ and flexibility by deferring most of its structure to the protocol
+ indicated by the URI scheme. Note that a resource can be identified
+ by a URI with a dereferenceable scheme, yet not be accessible over
+ that protocol. While currently very loose, this section is expected
+ to become more well-defined based on draft feedback, and may change
+ significantly in future drafts.
+
+
+
+ The value of this property is advisory only. It represents information that
+ is expected to be discoverable through interacting with the target resource,
+ typically in the form of protocol-specific control information or meta-data
+ such as headers returned in response to an HTTP HEAD or OPTIONS request.
+ The protocol is determined by the "href" URI scheme, although note that
+ resources are not guaranteed to be accessible over such a protocol.
+
+
+ The value of this property SHOULD be an object. The keys to this object
+ SHOULD be lower-cased forms of the control data field names. Each value
+ SHOULD be an array, in order to uniformly handle multi-valued fields.
+ Multiple values MUST be presented as an array, and not as a single string.
+
+
+ Protocols with control information not suitable for representation as
+ a JSON object MAY be represented by another data type, such as an array.
+
+
+ Values that cannot be understood as part of the indicated protocol MUST
+ be ignored by a JSON Hyper-Schema implementation. Applications MAY make
+ use of such values, but MUST NOT assume interoperability with other
+ implementations.
+
+
+ Implementations MUST NOT assume that all discoverable information is
+ accounted for in this object. Clients MUST properly handle run-time responses
+ that contradict this property's values.
+
+
+ Clients MUST NOT assume that an implementation will automatically take any
+ action based on the value of this property.
+
+
+
+ It would be good to also include a section with CoAP examples.
+
+
+ JSON serializations of HTTP response header information SHOULD follow the
+ guidelines established by the work in progress
+ "A JSON Encoding for HTTP Header Field Values".
+ Approaches shown in that document's examples SHOULD be applied to other
+ similarly structured headers wherever possible.
+
+
+ No distinction is made between headers that may appear in responses to
+ different methods, such as HEAD vs OPTIONS.
+
+
+
+ This examples shows several hints that are useful for clients
+ when determining what requests to make and how to make them.
+
+
+
+
+
+
+
+
The value of this property is advisory only, and represents the media type
@@ -1059,7 +1138,8 @@ GET /foo/
If this property's value is not specified, then the value should be taken to be
- "application/json".
+ "application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific
+ value in "targetHints" for this purpose.
@@ -1235,6 +1315,7 @@ GET /foo/
&rfc3986;
&rfc6570;
+ &I-D.reschke-http-jfv;
JSON Schema: A Media Type for Describing JSON Documents
diff --git a/links.json b/links.json
index b1fc2ed3..76be45b1 100644
--- a/links.json
+++ b/links.json
@@ -32,6 +32,9 @@
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
]
},
+ "targetHints": {
+ "description": "JSON representation of likely metadata such as response headers, with a protocol-dependent format"
+ },
"mediaType": {
"type": "string"
},