Skip to content

Commit a6085fe

Browse files
committed
More guidance on HTTP and headerSchema
This is another very vague and open-ended feature. Provide more guidance on what headers are and are not useful to describe.
1 parent a333e40 commit a6085fe

File tree

1 file changed

+18
-3
lines changed

1 file changed

+18
-3
lines changed

jsonschema-hyperschema.xml

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1378,12 +1378,27 @@ GET /foo/
13781378
other similarly structured headers wherever possible.
13791379
</t>
13801380
<t>
1381-
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1382-
is a good candidate for description in "headerSchema". It defines
1383-
several standard values and allows for extension values.
1381+
It is RECOMMENDED that schema authors describe the available usage of
1382+
the following types of HTTP headers whenever applicable:
1383+
<list style="symbols">
1384+
<t>Content negotiation</t>
1385+
<t>Authentication and authorization</t>
1386+
<t>Range requests</t>
1387+
<t>The "Prefer" header</t>
1388+
</list>
1389+
</t>
1390+
<t>
1391+
Headers such as cache control and conditional request headers are generally
1392+
implemented by intermediaries rather than the resource, and are therefore
1393+
not generally useful to describe. While the resource must supply the
1394+
information needed to use conditional requests, the runtime handling of
1395+
such headers and related responses is not resource-specific.
13841396
</t>
13851397
<figure>
13861398
<preamble>
1399+
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1400+
is a good candidate for description in "headerSchema". It defines
1401+
several standard values and allows for extension values.
13871402
This schema indicates that the target understands the
13881403
"respond-async" preference, the "wait" preference which
13891404
takes a number of seconds to wait, as well as "minimal" and

0 commit comments

Comments
 (0)