Skip to content

Commit 0c48470

Browse files
handrewshandrews
authored
Merge pull request #449 from handrews/req-resp
Add request/response implementation requirements
2 parents 7546fb0 + 494e298 commit 0c48470

File tree

1 file changed

+83
-18
lines changed

1 file changed

+83
-18
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 83 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -207,6 +207,14 @@
207207
command-line arguments, configuration files, or hardcoded values
208208
in source code.
209209
</t>
210+
<t hangText="operation">
211+
A specific use of a hyperlink, such as making a network request
212+
(for a URI with a scheme such as "http://" that indicates a protocol)
213+
or otherwise taking action based on a link (reading data from a
214+
"data:" URI, or constructing an email message based on a "mailto:"
215+
link). For protocols such as HTTP that support multiple methods,
216+
each method is considered to be a separate operation on the same link.
217+
</t>
210218
</list>
211219
</t>
212220
</section>
@@ -1186,24 +1194,81 @@ for varname in templateData:
11861194
</t>
11871195
</section>
11881196

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

@@ -2199,7 +2264,7 @@ Link: <https://schema.example.com/entry> rel=describedBy
21992264
information that is provided beyond the protocol's own status reporting.
22002265
</t>
22012266
</section>
2202-
<section title="Static analysis of an API's hyper-schemas">
2267+
<section title="Static analysis of an API's hyper-schemas" anchor="staticAnalysis">
22032268
<t>
22042269
It is possible to statically analyze a set of hyper-schemas without instance
22052270
data in order to generate output such as documentation or code. However,

0 commit comments

Comments
 (0)