From ddbe824f3d3e595a301242e484559f91b899a676 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 30 Aug 2017 21:02:06 -0700 Subject: [PATCH 1/3] Add "targetHints" This is a very tentative first pass to get the discussion started. The goal for this draft is to specify this well enough to get real-world implementations and feedback. It seems best to approach that goal by providing loose guidelines and encouraging experimentation. The lack of a standard way to advertise HTTP method support, for instance, is a major barrier to adoption for many who have expressed interest in Hyper-Schema. Including an approach that will easily fulfill that need while encouraging feedback on what further guidance is needed for more comprehensive use is preferable to waiting another draft while we come up with a solid proposal. That still might not hold up in the real world anyway. This will be more useful for feedback than simply providing an "allow" keyword, as it will encourage exploring other use cases, which a narrowly targeted "allow" keyword would not. --- jsonschema-hyperschema.xml | 85 +++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 3e0cfcf4..7e54eccd 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -10,6 +10,7 @@ + ]> @@ -1028,6 +1029,86 @@ GET /foo/ +
+ + + This section attempts to strike a balance between comprehensiveness + and flexibility by deferring most of its structure to the protocol + indicated by the URI scheme. Note that a resource can be identified + by a URI with a dereferenceable scheme, yet not be accessible over + that protocol. While currently very loose, this section is expected + to become more well-defined based on draft feedback, and may change + significantly in future drafts. + + + + The value of this property is advisory only. It represents information that + is expected to be discoverable through interacting with the target resource, + typically in the form of protocol-specific control information or meta-data + such as headers returned in response to an HTTP HEAD or OPTIONS request. + The protocol is determined by the "href" URI scheme, although note that + resources are not guaranteed to be accessible over such a protocol. + + + The value of this property SHOULD be an object. The keys to this object + SHOULD be lower-cased forms of the control data field names. Each value + SHOULD be an array, in order to uniformly handle multi-valued fields. + Multiple values MUST be presented as an array, and not as a single string. + + + Protocols with control information not suitable for representation as + a JSON object MAY be represented by another data type, such as an array. + + + Values that cannot be understood as part of the indicated protocol MUST + be ignored by a JSON Hyper-Schema implementation. Applications MAY make + use of such values, but MUST NOT assume interoperability with other + implementations. + + + Implementations MUST NOT assume that all discoverable information is + accounted for in this object. Clients MUST properly handle run-time responses + that contradict this property's values. + + + Clients MUST NOT assume that an implementation will automatically take any + action based on the value of this property. + +
+ + JSON serializations of HTTP response header information SHOULD follow the + 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. + + + No distinction is made between headers that may appear in responses to + different methods, such as HEAD vs OPTIONS. + +
+ + This examples shows several hints that are useful for clients + when determining what requests to make and how to make them. + + + + +
+
+
+ + TBD + +
+
+
The value of this property is advisory only, and represents the media type @@ -1059,7 +1140,8 @@ GET /foo/ If this property's value is not specified, then the value should be taken to be - "application/json". + "application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific + value in "targetHints" for this purpose.
@@ -1235,6 +1317,7 @@ GET /foo/ &rfc3986; &rfc6570; + &I-D.reschke-http-jfv; JSON Schema: A Media Type for Describing JSON Documents From ede1785ebd80f5b69930a9538605c6b5684d4d31 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 31 Aug 2017 09:32:06 -0700 Subject: [PATCH 2/3] Put CoAP TBD in a cref instead of text. --- jsonschema-hyperschema.xml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7e54eccd..5f5f2a0b 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -1075,6 +1075,9 @@ GET /foo/ action based on the value of this property.
+ + It would be good to also include a section with CoAP examples. + JSON serializations of HTTP response header information SHOULD follow the guidelines established by the work in progress @@ -1102,11 +1105,6 @@ GET /foo/
-
- - TBD - -
From 7c8d55d815ae7b65218e14cd5a27e035b84571f8 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 12 Sep 2017 17:54:30 -0700 Subject: [PATCH 3/3] Add targetHints to links.json --- links.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/links.json b/links.json index b1fc2ed3..76be45b1 100644 --- a/links.json +++ b/links.json @@ -32,6 +32,9 @@ { "$ref": "http://json-schema.org/draft-06/hyper-schema#" } ] }, + "targetHints": { + "description": "JSON representation of likely metadata such as response headers, with a protocol-dependent format" + }, "mediaType": { "type": "string" },