Skip to content

Commit 7f401b2

Browse files
handrewshandrews
authored
Merge pull request #383 from handrews/hints
Add "targetHints"
2 parents 67ff041 + 7c8d55d commit 7f401b2

File tree

2 files changed

+85
-1
lines changed

2 files changed

+85
-1
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 82 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"?>
@@ -1028,6 +1029,84 @@ GET /foo/
10281029
</section>
10291030
</section>
10301031

1032+
<section title="targetHints" anchor="targetHints">
1033+
<t>
1034+
<cref>
1035+
This section attempts to strike a balance between comprehensiveness
1036+
and flexibility by deferring most of its structure to the protocol
1037+
indicated by the URI scheme. Note that a resource can be identified
1038+
by a URI with a dereferenceable scheme, yet not be accessible over
1039+
that protocol. While currently very loose, this section is expected
1040+
to become more well-defined based on draft feedback, and may change
1041+
significantly in future drafts.
1042+
</cref>
1043+
</t>
1044+
<t>
1045+
The value of this property is advisory only. It represents information that
1046+
is expected to be discoverable through interacting with the target resource,
1047+
typically in the form of protocol-specific control information or meta-data
1048+
such as headers returned in response to an HTTP HEAD or OPTIONS request.
1049+
The protocol is determined by the "href" URI scheme, although note that
1050+
resources are not guaranteed to be accessible over such a protocol.
1051+
</t>
1052+
<t>
1053+
The value of this property SHOULD be an object. The keys to this object
1054+
SHOULD be lower-cased forms of the control data field names. Each value
1055+
SHOULD be an array, in order to uniformly handle multi-valued fields.
1056+
Multiple values MUST be presented as an array, and not as a single string.
1057+
</t>
1058+
<t>
1059+
Protocols with control information not suitable for representation as
1060+
a JSON object MAY be represented by another data type, such as an array.
1061+
</t>
1062+
<t>
1063+
Values that cannot be understood as part of the indicated protocol MUST
1064+
be ignored by a JSON Hyper-Schema implementation. Applications MAY make
1065+
use of such values, but MUST NOT assume interoperability with other
1066+
implementations.
1067+
</t>
1068+
<t>
1069+
Implementations MUST NOT assume that all discoverable information is
1070+
accounted for in this object. Clients MUST properly handle run-time responses
1071+
that contradict this property's values.
1072+
</t>
1073+
<t>
1074+
Clients MUST NOT assume that an implementation will automatically take any
1075+
action based on the value of this property.
1076+
</t>
1077+
<section title='"targetHints" for HTTP'>
1078+
<t>
1079+
<cref>It would be good to also include a section with CoAP examples.</cref>
1080+
</t>
1081+
<t>
1082+
JSON serializations of HTTP response header information SHOULD follow the
1083+
guidelines established by the work in progress
1084+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>.
1085+
Approaches shown in that document's examples SHOULD be applied to other
1086+
similarly structured headers wherever possible.
1087+
</t>
1088+
<t>
1089+
No distinction is made between headers that may appear in responses to
1090+
different methods, such as HEAD vs OPTIONS.
1091+
</t>
1092+
<figure>
1093+
<preamble>
1094+
This examples shows several hints that are useful for clients
1095+
when determining what requests to make and how to make them.
1096+
</preamble>
1097+
<artwork>
1098+
<![CDATA[{
1099+
"targetHints": {
1100+
"allow": ["GET", "PUT"],
1101+
"accept-patch": ["application/merge-patch+json"],
1102+
"accept-ranges": ["none"]
1103+
}
1104+
}]]>
1105+
</artwork>
1106+
</figure>
1107+
</section>
1108+
</section>
1109+
10311110
<section title="mediaType">
10321111
<t>
10331112
The value of this property is advisory only, and represents the media type
@@ -1059,7 +1138,8 @@ GET /foo/
10591138

10601139
<t>
10611140
If this property's value is not specified, then the value should be taken to be
1062-
"application/json".
1141+
"application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific
1142+
value in <xref target="targetHints">"targetHints"</xref> for this purpose.
10631143
</t>
10641144

10651145
<figure>
@@ -1235,6 +1315,7 @@ GET /foo/
12351315
&rfc3986;
12361316
<!--&rfc4287;-->
12371317
&rfc6570;
1318+
&I-D.reschke-http-jfv;
12381319
<reference anchor="json-schema">
12391320
<front>
12401321
<title>JSON Schema: A Media Type for Describing JSON Documents</title>

‎links.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@
3232
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
3333
]
3434
},
35+
"targetHints": {
36+
"description": "JSON representation of likely metadata such as response headers, with a protocol-dependent format"
37+
},
3538
"mediaType": {
3639
"type": "string"
3740
},

0 commit comments

Comments
 (0)