Add "targetHints" #383
Add "targetHints" #383
Conversation
There was a problem hiding this comment.
Looks reasonable overall.
-
The second commit's message mentions "anchorHints", it should be "targetHints".
-
I'm not sure we need the CoAP example (currently TBD) in a first version. I guess the HTTP example could be ported to another protocol without being explicitly written here, or maybe leave this for actual users that might come up with more relevant examples.
jsonschema-hyperschema.xml
Outdated
| <t> | ||
| 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 hanlde multi-valued fields. |
Well we don't need it. But IoT folks use CBOR and CoAP and are an increasing presence. I'm not going to delay anything for it, just wanted to remember to see if anyone would take a shot. |
handrews
force-pushed
the
hints
branch
2 times, most recently
from
11943d8 to
5cef9f9
Compare
|
@dlax I have fixed the typo (and another one- quote in the wrong place on targetHints for HTTP title) although I squashed them into the first commit (long-standing habit and I didn't think to leave the split for review, sorry). I also moved the CoAP thing into a cref comment and out of the main text (this is it's own commit) and reworded the meta-schema commit message. |
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#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.
|
Last call! This will get merged tomorrow otherwise. I expect it to evolve further based on feedback, and there are cref notes to that effect in the XML source. The commit I just pushed adds the keyword to link.json, which I forgot. It's a direct copy from hyper-schema.json so I'm not waiting on a separately review. I loaded links.json through a JSON parser to make sure I didn't break the file. |
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#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.
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.
|
Updated on top of #406 which only affected links.json and hyper-schema.json |
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#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.
| @@ -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" | |||
There was a problem hiding this comment.
Hm, didn't we just removed "description"?
(Will send a PR to fix that.)
There was a problem hiding this comment.
Ugh, yes. I've been rebasing and fixing these all evening. Missed this one.
We just removed all descriptions in 0b0681c; that one slipped in when PR json-schema-org#383 got rebased (and merged).
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#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.
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#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.
This is a very tentative first pass to get the discussion started.
This addresses half of #296, specifically advertising information
about the target that would likely be discovered through mechanism
such as the headers of an HTTP HEAD and/or OPTIONS response.
The half for describing request header (or analogous) data will
be posted separately after we see how this goes.
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.
This draft needs to include an approach that will at least
easily fulfill that need while encouraging feedback on what
further guidance is needed for more comprehensive use.
Waiting for the next draft to work up a more detailed
proposal that might not hold up in the wild anyway will
only delay adoption and feedback.
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.