From e5b20256e4f78f60bd128fb98330034c4cc28fe3 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 2 Sep 2017 00:16:20 -0700 Subject: [PATCH 1/4] Add "headerSchema" This addresses the request half of #296, and is a companion keyword to "targetHints" (#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here. --- jsonschema-hyperschema.xml | 119 +++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 658e0371..74dc67cb 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -10,6 +10,7 @@ + ]> @@ -1187,6 +1188,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 @@ -1310,6 +1428,7 @@ GET /foo/ &rfc5789; &rfc5988; &rfc7231; + &rfc7240;
From a79a9130167137270dd3c9224ae18714e6352902 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 12 Sep 2017 17:53:07 -0700 Subject: [PATCH 2/4] Add headerSchema to links.json --- links.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/links.json b/links.json index 70af192b..f079efd4 100644 --- a/links.json +++ b/links.json @@ -43,6 +43,12 @@ "mediaType": { "type": "string" }, + "headerSchema": { + "description": "Schema for protocol-specific headers or analogous data, as signified by URI scheme", + "allOf": [ + { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } + ] + }, "submissionEncType": { "type": "string", "default": "application/json" From 4f56c74e63d48e228917b75c1d45b7b60d8d6471 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 13 Sep 2017 23:32:11 -0700 Subject: [PATCH 3/4] Fix typo. --- jsonschema-hyperschema.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 74dc67cb..8a916d9c 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1192,7 +1192,7 @@ GET /foo/ As with "targetHints", this keyword is somewhat under-specified - to encourage experiementation and feedback as we try to balance + to encourage experimentation and feedback as we try to balance flexibility and clarity. From 6a496cf65ec80f14d3183fe881eb2efc229d823d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 14 Sep 2017 00:01:54 -0700 Subject: [PATCH 4/4] Remove headerSchema description from links.json --- links.json | 1 - 1 file changed, 1 deletion(-) diff --git a/links.json b/links.json index f079efd4..4d8dddb0 100644 --- a/links.json +++ b/links.json @@ -44,7 +44,6 @@ "type": "string" }, "headerSchema": { - "description": "Schema for protocol-specific headers or analogous data, as signified by URI scheme", "allOf": [ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ]