diff --git a/hyper-schema.json b/hyper-schema.json index 84249f01..37bbf39c 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -41,6 +41,10 @@ "description": "media type (as defined by RFC 2046) describing the link target", "type": "string" }, + "headerSchema": { + "description": "Schema for protocol-specific headers or analogous data, as signified by URI scheme", + "allOf": [ { "$ref": "#" } ] + }, "submissionEncType": { "description": "The media type in which to submit data along with the request", "type": "string", diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index a1c1eae2..4051e8a1 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -10,6 +10,8 @@ + + ]> @@ -1095,6 +1097,123 @@ GET /foo/ +
+ + + As with "targetHints", this keyword is somewhat under-specified + to encourage experiementation and feedback as we try to balance + flexibility and clarity. + + + + If present, this property is a schema for protocol-specific request + headers or analogous control and meta-data. The value of this + object MUST be a valid JSON Schema. + The protocol is determined by the "href" URI scheme, although note that + resources are not guaranteed to be accessible over such a protocol. + The schema is advisory only; the target resource's behavior is not + constrained by its presence. + + + The purpose of this keyword is to advertise target resource interaction + features, and indicate to clients what headers and header values are + likely to be useful. Clients MAY use the schema to validate relevant + headers, but MUST NOT assume that missing headers or values are forbidden + from use. While schema authors MAY set "additionalProperties" to + false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents + from supplying additional headers when requests are made. + + + The exact mapping of the JSON data model into the headers is + protocol-dependent. However, in most cases this schema SHOULD + specify a type of "object", and the property names SHOULD be + lower-cased forms of the control data field names. + + + "headerSchema" is applicable to any request method or command that the + protocol supports. When generating a request, clients SHOULD ignore + schemas for headers that are not relevant to that request. + +
+ + Schemas SHOULD be written to describe JSON serializations that + follow 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. + + + 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. + + +
+
+
If present, this property indicates the media type format the @@ -1216,6 +1335,8 @@ GET /foo/ &rfc5789; &rfc5988; &rfc7231; + &rfc7240; + &I-D.reschke-http-jfv;