Skip to content

Commit 3d5b93d

Browse files
handrewshandrews
committed
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.
1 parent 3b17738 commit 3d5b93d

File tree

1 file changed

+84
-1
lines changed

1 file changed

+84
-1
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1111
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
1212
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
13+
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1314
]>
1415
<?rfc toc="yes"?>
1516
<?rfc symrefs="yes"?>
@@ -974,6 +975,86 @@ GET /foo/
974975
</section>
975976
</section>
976977

978+
<section title="targetHints" anchor="targetHints">
979+
<t>
980+
<cref>
981+
This section attempts to strike a balance between comprehensiveness
982+
and flexibility by deferring most of its structure to the protocol
983+
indicated by the URI scheme. Note that a resource can be identified
984+
by a URI with a dereferenceable scheme, yet not be accessible over
985+
that protocol. While currently very loose, this section is expected
986+
to become more well-defined based on draft feedback, and may change
987+
significantly in future drafts.
988+
</cref>
989+
</t>
990+
<t>
991+
The value of this property is advisory only. It represents information that
992+
is expected to be discoverable through interacting with the target resource,
993+
typically in the form of protocol-specific control information or meta-data
994+
such as headers returned in response to an HTTP HEAD or OPTIONS request.
995+
The protocol is determined by the "href" URI scheme, although note that
996+
resources are not guaranteed to be accessible over such a protocol.
997+
</t>
998+
<t>
999+
The value of this property SHOULD be an object. The keys to this object
1000+
SHOULD be lower-cased forms of the control data field names. Each value
1001+
SHOULD be an array, in order to uniformly handle multi-valued fields.
1002+
Multiple values MUST be presented as an array, and not as a single string.
1003+
</t>
1004+
<t>
1005+
Protocols with control information not suitable for representation as
1006+
a JSON object MAY be represented by another data type, such as an array.
1007+
</t>
1008+
<t>
1009+
Values that cannot be understood as part of the indicated protocol MUST
1010+
be ignored by a JSON Hyper-Schema implementation. Applications MAY make
1011+
use of such values, but MUST NOT assume interoperability with other
1012+
implementations.
1013+
</t>
1014+
<t>
1015+
Implementations MUST NOT assume that all discoverable information is
1016+
accounted for in this object. Clients MUST properly handle run-time responses
1017+
that contradict this property's values.
1018+
</t>
1019+
<t>
1020+
Clients MUST NOT assume that an implementation will automatically take any
1021+
action based on the value of this property.
1022+
</t>
1023+
<section title='"targetHints for HTTP"'>
1024+
<t>
1025+
JSON serializations of HTTP response header information SHOULD follow the
1026+
guidelines established by the work in progress
1027+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>.
1028+
Approaches shown in that document's examples SHOULD be applied to other
1029+
similarly structured headers wherever possible.
1030+
</t>
1031+
<t>
1032+
No distinction is made between headers that may appear in responses to
1033+
different methods, such as HEAD vs OPTIONS.
1034+
</t>
1035+
<figure>
1036+
<preamble>
1037+
This examples shows several hints that are useful for clients
1038+
when determining what requests to make and how to make them.
1039+
</preamble>
1040+
<artwork>
1041+
<![CDATA[{
1042+
"targetHints": {
1043+
"allow": ["GET", "PUT"],
1044+
"accept-patch": ["application/merge-patch+json"],
1045+
"accept-ranges": ["none"]
1046+
}
1047+
}]]>
1048+
</artwork>
1049+
</figure>
1050+
</section>
1051+
<section title='"targetHints for CoAP"'>
1052+
<t>
1053+
<cref>TBD</cref>
1054+
</t>
1055+
</section>
1056+
</section>
1057+
9771058
<section title="mediaType">
9781059
<t>
9791060
The value of this property is advisory only, and represents the media type
@@ -1005,7 +1086,8 @@ GET /foo/
10051086

10061087
<t>
10071088
If this property's value is not specified, then the value should be taken to be
1008-
"application/json".
1089+
"application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific
1090+
value in <xref target="targetHints">"targetHints"</xref> for this purpose.
10091091
</t>
10101092

10111093
<figure>
@@ -1181,6 +1263,7 @@ GET /foo/
11811263
&rfc3986;
11821264
<!--&rfc4287;-->
11831265
&rfc6570;
1266+
&I-D.reschke-http-jfv;
11841267
<reference anchor="json-schema">
11851268
<front>
11861269
<title>JSON Schema: A Media Type for Describing JSON Documents</title>

0 commit comments

Comments
 (0)