diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 8614d845..cffc59bd 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -13,6 +13,7 @@ + @@ -1394,6 +1395,21 @@ for varname in templateData: In general, headers that are likely to have different values at different times SHOULD NOT be included in "targetHints". +
+ + This examples shows several hints that are useful for clients + when determining what requests to make and how to make them. + + + + +
@@ -1420,6 +1436,75 @@ for varname in templateData: 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 + "representation" for the "return" preference. + + + + + + Each name/value preference pair is a single value of the + header, so each object in the list can only have one such + pair. Simplifying the "response-async" value to a single string + is based on the "Accept-Encoding" example in + appendix A.4 of the JSON encoding draft. + +
+ + The Prefer header also stretches the limits of existing recommendations + for serializing HTTP headers in JSON. It is possible for both the + single string and name/value pair preferences to take additional + name/value parameters. While a single-string preference can accomodate + such parameters following the "Accept-Encoding" example, there is + no example to date of a name/value pair with parameters. + + We hope to get feedback from hyper-schema authors on what + practical concerns arise, and from there decide how best to + handle them. The specification for this keyword is expected to + become more well-defined in future drafts. + +
@@ -2331,6 +2416,7 @@ Link: rev=up &rfc6573; &rfc7230; &rfc7231; + &rfc7240; &rfc7807; &rfc8288;