Skip to content

Commit d9864a4

Browse files
handrewshandrews
committed
Add request/response implementation requirements
This mostly involves explaining that hyper-schema is not a system for executing requests and processing response. It informs a user agent how to construct various requests, and is used to interpret whatever response (expected, error, whatever) is returned.
1 parent 0702982 commit d9864a4

File tree

1 file changed

+84
-19
lines changed

1 file changed

+84
-19
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 84 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,14 @@
206206
command-line arguments, configuration files, or hardcoded values
207207
in source code.
208208
</t>
209+
<t hangText="operation">
210+
A specific use of a hyperlink, such as making a network request
211+
(for a URI with a scheme such as "http://" that indicates a protocol)
212+
or otherwise taking action based on a link (reading data from a
213+
"data:" URI, or constructing an email message based on a "mailto:"
214+
link). For protocols such as HTTP that support multiple methods,
215+
each method is considered to be a separate operation on the same link.
216+
</t>
209217
</list>
210218
</t>
211219
</section>
@@ -439,7 +447,7 @@
439447
<section title='"self" links' anchor="self">
440448
<t>
441449
A hyper-schema implementation MUST recognize that a link with relation
442-
type "self" that is applicable to the entire instance document describes
450+
type "self" that is applicable to the entire instance document describes
443451
how a user agent can interact with the resource represented by that
444452
instance document. A "self" link MUST be resolvable from the instance,
445453
and therefore "hrefSchema" MUST NOT be present.
@@ -1183,24 +1191,81 @@ for varname in templateData:
11831191
</t>
11841192
</section>
11851193

1186-
<section title="Additional functionality">
1194+
<section title="Requests">
11871195
<t>
1188-
Implementations MAY provide additional functionality coordinating the use of
1189-
JSON Hyper-Schema with other specifications, including but not limited to
1190-
JSON Schema validation, serializing payloads based on media types, and
1191-
communicating with resources via protocols as indicated by URI schemes.
1192-
<cref>
1193-
This is vague. I'm trying to convey that most uses of Hyper-Schema
1194-
would benefit from including integration with the media types, URI schemes,
1195-
and protocols, such as automatically validating submission data against
1196-
"submissionSchema", encoding it according to "submissionMediaType",
1197-
examining the URI for the "http" or "https" scheme, validating JSON
1198-
representations of headers against "headerSchema", serializing them
1199-
into HTTP header format, and constructing the appropriate POST request.
1200-
While many of those activities are technically outside of the scope of
1201-
Hyper-Schema, coordinating all of them is specific to Hyper-Schema and
1202-
beneficial to automate.
1203-
</cref>
1196+
A hyper-schema implementation SHOULD provide access to all information
1197+
needed to construct any valid request to the target resource.
1198+
</t>
1199+
<t>
1200+
The LDO can express all information needed to perform any operation on
1201+
a link. This section explains what hyper-schema fields a user agent
1202+
should examine to build requests from any combination of instance data
1203+
and client input. A hyper-schema implementation is not itself expected
1204+
to construct and send requests.
1205+
</t>
1206+
<t>
1207+
Target URI construction rules, including "hrefSchema" for accepting input,
1208+
are identical for all possible requests.
1209+
</t>
1210+
<t>
1211+
Requests that do not carry a body payload do not require additional keyword
1212+
support.
1213+
</t>
1214+
<t>
1215+
Requests that take a target representation as a payload SHOULD use the
1216+
"targetSchema" and "targetMediaTYpe" keywords for input description and
1217+
payload validation. If a protocol allows an operation taking a payload
1218+
that is based on the representation as modified by a media type
1219+
(such as a patch media type), then such a media type SHOULD be indicated
1220+
through "targetHints" in a protocol-specific manner.
1221+
</t>
1222+
<t>
1223+
Requests that take a payload that is not derived from the target resource's
1224+
representation SHOULD use the "submissionSchema" and "submissionMediaType"
1225+
keywords for input description and payload validation. Protocols used in
1226+
hypermedia generally only support one such non-representation operation
1227+
per link.
1228+
</t>
1229+
<t>
1230+
RPC systems that pipe many application operations with arbitrarily different
1231+
request structures through a single hypermedia protocol operation are outside
1232+
of the scope of a hypermedia format such as JSON Hyper-Schema.
1233+
</t>
1234+
</section>
1235+
1236+
<section title="Responses">
1237+
<t>
1238+
As a hypermedia format, JSON Hyper-Schema is concerned with describing
1239+
a resource, including describing its links in sufficient detail to make
1240+
all valid requests. It is not concerned with directly describing all
1241+
possible responses for those requests.
1242+
</t>
1243+
<t>
1244+
As in any hypermedia system, responses are expected to be self-describing.
1245+
In the context of hyper-schema, this means that each response MUST link
1246+
its own hyper-schema(s). While responses that consist of a representation
1247+
of the target resource are expected to be valid against "targetSchema"
1248+
and "targetMediaType", those keywords are advisory only and MUST be
1249+
ignored if contradicted by the response itself.
1250+
</t>
1251+
<t>
1252+
Other responses, including error responses, complex redirections, and
1253+
processing status representations SHOULD also link to their own schemas
1254+
and use appropriate media types
1255+
(e.g. <xref target="RFC7807">"application/problem+json"</xref> for errors).
1256+
Certain errors might not link a schema due to being generated by an
1257+
intermediary that is not aware of hyper-schema, rather than by the origin.
1258+
</t>
1259+
<t>
1260+
User agents are expected to understand protocol status codes and response
1261+
media types well enough to handle common situations, and provide enough
1262+
information to client applications to handle domain-specific responses.
1263+
</t>
1264+
<t>
1265+
Statically mapping all possible responses and their schemas at design time
1266+
is outside of the scope of JSON Hyper-Schema, but may be within the scope
1267+
of other JSON Schema vocabularies which build on hyper-schema
1268+
(see <xref target="staticAnalysis" />).
12041269
</t>
12051270
</section>
12061271

@@ -1542,7 +1607,7 @@ for varname in templateData:
15421607
information that is provided beyond the protocol's own status reporting.
15431608
</t>
15441609
</section>
1545-
<section title="Static analysis of an API's hyper-schemas">
1610+
<section title="Static analysis of an API's hyper-schemas" anchor="staticAnalysis">
15461611
<t>
15471612
It is possible to statically analyze a set of hyper-schemas without instance
15481613
data in order to generate output such as documentation or code. However,

0 commit comments

Comments
 (0)