diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
index 75e836a8..a5463207 100644
--- a/jsonschema-hyperschema.xml
+++ b/jsonschema-hyperschema.xml
@@ -1183,6 +1183,19 @@ GET /foo/
Approaches shown in that document's examples SHOULD be applied to other
similarly structured headers wherever possible.
+
+ It is RECOMMENDED that schema authors provide hints for the values of
+ the following types of HTTP headers whenever applicable:
+
+ Method allowance
+ Method-specific request media types
+ Authentication challenges
+
+
+
+ In general, headers that are likely to have different values at different
+ times SHOULD NOT be included in "targetHints".
+
No distinction is made between headers that may appear in responses to
different methods, such as HEAD vs OPTIONS.
@@ -1365,12 +1378,27 @@ GET /foo/
other similarly structured headers wherever possible.
- The "Prefer" header defined in RFC 7240
- 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:
+
+ Content negotiation
+ Authentication and authorization
+ Range requests
+ The "Prefer" header
+
+
+
+ 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.
+ The "Prefer" header defined in RFC 7240
+ 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