|
9 | 9 | <!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
|
10 | 10 | <!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
|
11 | 11 | <!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
|
| 12 | +<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml"> |
12 | 13 | ]>
|
13 | 14 | <?rfc toc="yes"?>
|
14 | 15 | <?rfc symrefs="yes"?>
|
@@ -904,6 +905,84 @@ GET /foo/
|
904 | 905 | </section>
|
905 | 906 | </section>
|
906 | 907 |
|
| 908 | + <section title="targetHints" anchor="targetHints"> |
| 909 | + <t> |
| 910 | + <cref> |
| 911 | + This section attempts to strike a balance between comprehensiveness |
| 912 | + and flexibility by deferring most of its structure to the protocol |
| 913 | + indicated by the URI scheme. Note that a resource can be identified |
| 914 | + by a URI with a dereferenceable scheme, yet not be accessible over |
| 915 | + that protocol. While currently very loose, this section is expected |
| 916 | + to become more well-defined based on draft feedback, and may change |
| 917 | + significantly in future drafts. |
| 918 | + </cref> |
| 919 | + </t> |
| 920 | + <t> |
| 921 | + The value of this property is advisory only. It represents information that |
| 922 | + is expected to be discoverable through interacting with the target resource, |
| 923 | + typically in the form of protocol-specific control information or meta-data |
| 924 | + such as headers returned in response to an HTTP HEAD or OPTIONS request. |
| 925 | + The protocol is determined by the "href" URI scheme, although note that |
| 926 | + resources are not guaranteed to be accessible over such a protocol. |
| 927 | + </t> |
| 928 | + <t> |
| 929 | + The value of this property SHOULD be an object. The keys to this object |
| 930 | + SHOULD be lower-cased forms of the control data field names. Each value |
| 931 | + SHOULD be an array, in order to uniformly handle multi-valued fields. |
| 932 | + Multiple values MUST be presented as an array, and not as a single string. |
| 933 | + </t> |
| 934 | + <t> |
| 935 | + Protocols with control information not suitable for representation as |
| 936 | + a JSON object MAY be represented by another data type, such as an array. |
| 937 | + </t> |
| 938 | + <t> |
| 939 | + Values that cannot be understood as part of the indicated protocol MUST |
| 940 | + be ignored by a JSON Hyper-Schema implementation. Applications MAY make |
| 941 | + use of such values, but MUST NOT assume interoperability with other |
| 942 | + implementations. |
| 943 | + </t> |
| 944 | + <t> |
| 945 | + Implementations MUST NOT assume that all discoverable information is |
| 946 | + accounted for in this object. Clients MUST properly handle run-time responses |
| 947 | + that contradict this property's values. |
| 948 | + </t> |
| 949 | + <t> |
| 950 | + Clients MUST NOT assume that an implementation will automatically take any |
| 951 | + action based on the value of this property. |
| 952 | + </t> |
| 953 | + <section title='"targetHints" for HTTP'> |
| 954 | + <t> |
| 955 | + <cref>It would be good to also include a section with CoAP examples.</cref> |
| 956 | + </t> |
| 957 | + <t> |
| 958 | + JSON serializations of HTTP response header information SHOULD follow the |
| 959 | + guidelines established by the work in progress |
| 960 | + <xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>. |
| 961 | + Approaches shown in that document's examples SHOULD be applied to other |
| 962 | + similarly structured headers wherever possible. |
| 963 | + </t> |
| 964 | + <t> |
| 965 | + No distinction is made between headers that may appear in responses to |
| 966 | + different methods, such as HEAD vs OPTIONS. |
| 967 | + </t> |
| 968 | + <figure> |
| 969 | + <preamble> |
| 970 | + This examples shows several hints that are useful for clients |
| 971 | + when determining what requests to make and how to make them. |
| 972 | + </preamble> |
| 973 | + <artwork> |
| 974 | +<![CDATA[{ |
| 975 | + "targetHints": { |
| 976 | + "allow": ["GET", "PUT"], |
| 977 | + "accept-patch": ["application/merge-patch+json"], |
| 978 | + "accept-ranges": ["none"] |
| 979 | + } |
| 980 | +}]]> |
| 981 | + </artwork> |
| 982 | + </figure> |
| 983 | + </section> |
| 984 | + </section> |
| 985 | + |
907 | 986 | <section title="mediaType">
|
908 | 987 | <t>
|
909 | 988 | The value of this property is advisory only, and represents the media type
|
@@ -935,7 +1014,8 @@ GET /foo/
|
935 | 1014 |
|
936 | 1015 | <t>
|
937 | 1016 | If this property's value is not specified, then the value should be taken to be
|
938 |
| - "application/json". |
| 1017 | + "application/json". Hyper-Schema authors SHOULD NOT use a protocol-specific |
| 1018 | + value in <xref target="targetHints">"targetHints"</xref> for this purpose. |
939 | 1019 | </t>
|
940 | 1020 |
|
941 | 1021 | <figure>
|
@@ -1110,6 +1190,7 @@ GET /foo/
|
1110 | 1190 | &rfc3986;
|
1111 | 1191 | <!--&rfc4287;-->
|
1112 | 1192 | &rfc6570;
|
| 1193 | + &I-D.reschke-http-jfv; |
1113 | 1194 | <reference anchor="json-schema">
|
1114 | 1195 | <front>
|
1115 | 1196 | <title>JSON Schema: A Media Type for Describing JSON Documents</title>
|
|
0 commit comments