You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 2, 2023. It is now read-only.
<pid="rfc.section.7.6.p.2">Such implementations MAY choose to return non-authoritative answers based on data processed to date. When offering this approach, implementations MUST be clear on the nature of the response, and MUST offer an option to block and wait until all data is processed and an authoritative answer can be returned. </p>
928
930
<h1id="rfc.section.8"><ahref="#rfc.section.8">8.</a><ahref="#HTTP" id="HTTP">JSON Hyper-Schema and HTTP</a></h1>
929
931
<pid="rfc.section.8.p.1">While JSON Hyper-Schema is a hypermedia format and therefore protocol-independent, it is expected that its most common use will be in HTTP systems, or systems using protocols such as CoAP that are explicitly analogous to HTTP. </p>
930
-
<pid="rfc.section.8.p.2">This section provides guidance on how to define links for use with each common HTTP method, and how collection resources impose additional constraints on the use of HTTP POST. Additionally, guidance is provided on hinting at HTTP response header values and describing possible HTTP request headers that are relevant to the given resource. </p>
932
+
<pid="rfc.section.8.p.2">This section provides guidance on how to use each common HTTP method with a link, and how colletion resources impose additional constraints on HTTP POST. Additionally, guidance is provided on hinting at HTTP response header values and describing possible HTTP request headers that are relevant to the given resource. </p>
933
+
<p><ahref="#json-schema">Section 11 of the JSON Schema core specification</a><citetitle="NONE">[json-schema]</cite> provides guidance on linking instances in a hypermedia system to their schemas. This may be done with network-accessible schemas, or may simply identify schemas which were pre-packaged within the client application. JSON Hyper-Schema intentionally does not constrain this mechanism, although it is RECOMMENDED that the techniques outlined in the core specification be used to whatever extent is possible. </p>
931
934
<h1id="rfc.section.8.1"><ahref="#rfc.section.8.1">8.1.</a> One link per target and relation type</h1>
932
935
<pid="rfc.section.8.1.p.1">Link Description Objects do not directly indicate what operations, such as HTTP methods, are supported by the target resource. Instead, operations should be inferred primarily from link <ahref="#rel">relation types</a><citetitle="NONE">[rel]</cite> and URI schemes. </p>
933
936
<pid="rfc.section.8.1.p.2">This means that for each target resource and link relation type pair, schema authors SHOULD only define a single LDO. While it is possible to use "allow" with "targetHints" to repeat a relation type and target pair with different HTTP methods marked as allowed, this is NOT RECOMMENDED and may not be well-supported by conforming implementations. </p>
@@ -936,7 +939,7 @@ <h1 id="rfc.section.8.1"><a href="#rfc.section.8.1">8.1.</a> One link per target
936
939
<h1id="rfc.section.8.2"><ahref="#rfc.section.8.2">8.2.</a><ahref="#targetHTTP" id="targetHTTP">"targetSchema" and HTTP</a></h1>
937
940
<pid="rfc.section.8.2.p.1">The relationship between a resource's representation and HTTP requests and responses is determined by <ahref="#RFC7231">RFC 7231, section 4.3.1 - "GET", section 4.3.4 "PUT", and section 3.1.4.2, "Content-Location"</a><citetitle="NONE">[RFC7231]</cite>. In particular, "targetSchema" suggests what a client can expect for the response to an HTTP GET or any response for which the "Content-Location" header is equal to the request URI, and what a client should send if it replaces the resource in an HTTP PUT request. </p>
938
941
<pid="rfc.section.8.2.p.2">The media type of the representation is given by the "targetMediaType" field. Alternatively, possible available media types MAY be advertised for HTTP-accessible resources using the "accept" field in "headerSchema", corresponding to the HTTP "Accept" header. </p>
939
-
<pid="rfc.section.8.2.p.3">Per <ahref="#RFC5789">RFC 5789</a><citetitle="NONE">[RFC5789]</cite>, the request structure for an HTTP PATCH is determined by the combination of "targetSchema" and the request media type, which is conveyed by the "Accept-Patch" header. Media types that are suitable for PATCH-ing define a syntax for expressing changes to a document, which can be applied to the representation described by "targetSchema" to determine the set of syntactically valid request payloads. </p>
942
+
<pid="rfc.section.8.2.p.3">Per <ahref="#RFC5789">RFC 5789</a><citetitle="NONE">[RFC5789]</cite>, the request structure for an HTTP PATCH is determined by the combination of "targetSchema" and the request media type, which is conveyed by the "Accept-Patch" header. Media types that are suitable for PATCH-ing define a syntax for expressing changes to a document, which can be applied to the representation described by "targetSchema" to determine the set of syntactically valid request payloads. Often, the simplest way to validate a PATCH is to apply it and validate the result as a normal representation. </p>
940
943
<pid="rfc.section.8.2.p.4">HTTP POST request payloads are described by the "submissionSchema" and "submissionMediaType" fields. Additionally, the "Accept-Post" header can be used to specify the necessary media type, and MAY be advertised via the "targetHints" field. <aid="CREF7" class="info">[CREF7]<spanclass="info">What happens if both are used? Also, "submissionSchema" is a MUST to support, while "targetHints" are at most a SHOULD. But forbidding the use of "Accept-Post" in "targetHints" seems incorrect. </span></a></p>
941
944
<h1id="rfc.section.8.3"><ahref="#rfc.section.8.3">8.3.</a> Optimizing HTTP discoverability with "targetHints"</h1>
942
945
<p><aid="CREF8" class="info">[CREF8]<spanclass="info">It would be good to also include a section with CoAP examples.</span></a></p>
@@ -967,6 +970,10 @@ <h1 id="rfc.section.8.4"><a href="#rfc.section.8.4">8.4.</a> Advertising HTTP fe
967
970
<pid="rfc.section.8.4.p.3">Headers such as cache control and conditional request headers are generally implemented by intermediaries rather than the resource, and are therefore not generally useful to describe. While the resource must supply the information needed to use conditional requests, the runtime handling of such headers and related responses is not resource-specific. </p>
968
971
<h1id="rfc.section.8.5"><ahref="#rfc.section.8.5">8.5.</a> Creating resources through collections</h1>
969
972
<pid="rfc.section.8.5.p.1">When using HTTP, or a protocol such as CoAP that is explicitly analogous to HTTP, this is done by POST-ing a representation of the individual resource to be created to the collection resource. The process for recognizing collection and item resources is described in <ahref="#collectionAndItem">Section 6.2.3</a>. </p>
973
+
<h1id="rfc.section.8.6"><ahref="#rfc.section.8.6">8.6.</a> Content negotiation and schema evolution</h1>
974
+
<pid="rfc.section.8.6.p.1">JSON Hyper-Schema facilitates HTTP content negotiation, and allows for a hybrid of the proactive and reactive strategies. As mentioned above, a hyper-schema can include a schema for HTTP headers such as "Accept", "Accept-Charset", "Accept-Language", etc with the "headerSchema" keyword. A user agent or client application can use information in this schema, such as an enumerated list of supported languages, in lieu of making an initial request to start the reactive negotiation process. </p>
975
+
<pid="rfc.section.8.6.p.2">In this way, the proactive content negotiation technique of setting these headers can be informed by server information about what values are possible, similar to examining a list of alternatives in reactive negotiation. </p>
976
+
<pid="rfc.section.8.6.p.3">For media types that allow specifying a schema as a media type parameter, the "Accept" values sent in a request or advertised in "headerSchema" can include the URI(s) of the schema(s) to which the negotiated representation is expected to conform. One possible use for schema parameters in content negotiation is if the resource has conformed to several different schema versions over time. The client can indicate what version(s) it understands in the "Accept" header in this way. </p>
<pid="rfc.section.9.p.1">This section shows how the keywords that construct URIs and JSON Pointers are used. The results are shown in the format used by the test suite. <aid="CREF9" class="info">[CREF9]<spanclass="info">Need to post that and link it, but it should be pretty self-explanatory to those of you reviewing things at this stage. </span></a></p>
972
979
<pid="rfc.section.9.p.2">Most other keywords are either straightforward ("title" and "description"), apply validation to specific sorts of input, requests, or responses, or have protocol-specific behavior. Examples demonstrating HTTP usage are available in <ahref="#HTTP">an Appendix</a><citetitle="NONE">[HTTP]</cite>. </p>
0 commit comments