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