Skip to content

Commit e5b2025

Browse files
handrewshandrews
committed
Add "headerSchema"
This addresses the request half of json-schema-org#296, and is a companion keyword to "targetHints" (json-schema-org#383). Like "targetHints", this is a rough first pass to get the discussion of specifics started. I expect it to be somewhat underspecified to encourage experimentation. I intentionally chose an example that is both very complex and very useful. It might also be worth putting up a simpler example. Although when this appears right after "targetHints", the simpler header value examples in that section will help motivate what is going on here.
1 parent fa8eb73 commit e5b2025

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎jsonschema-hyperschema.xml

+119
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
1111
<!ENTITY rfc6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
1212
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
13+
<!ENTITY rfc7240 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7240.xml">
1314
<!ENTITY I-D.luff-relative-json-pointer SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-luff-relative-json-pointer-00.xml">
1415
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1516
]>
@@ -1187,6 +1188,123 @@ GET /foo/
11871188
</section>
11881189
</section>
11891190

1191+
<section title="headerSchema" anchor="headerSchema">
1192+
<t>
1193+
<cref>
1194+
As with "targetHints", this keyword is somewhat under-specified
1195+
to encourage experiementation and feedback as we try to balance
1196+
flexibility and clarity.
1197+
</cref>
1198+
</t>
1199+
<t>
1200+
If present, this property is a schema for protocol-specific request
1201+
headers or analogous control and meta-data. The value of this
1202+
object MUST be a valid JSON Schema.
1203+
The protocol is determined by the "href" URI scheme, although note that
1204+
resources are not guaranteed to be accessible over such a protocol.
1205+
The schema is advisory only; the target resource's behavior is not
1206+
constrained by its presence.
1207+
</t>
1208+
<t>
1209+
The purpose of this keyword is to advertise target resource interaction
1210+
features, and indicate to clients what headers and header values are
1211+
likely to be useful. Clients MAY use the schema to validate relevant
1212+
headers, but MUST NOT assume that missing headers or values are forbidden
1213+
from use. While schema authors MAY set "additionalProperties" to
1214+
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
1215+
from supplying additional headers when requests are made.
1216+
</t>
1217+
<t>
1218+
The exact mapping of the JSON data model into the headers is
1219+
protocol-dependent. However, in most cases this schema SHOULD
1220+
specify a type of "object", and the property names SHOULD be
1221+
lower-cased forms of the control data field names.
1222+
</t>
1223+
<t>
1224+
"headerSchema" is applicable to any request method or command that the
1225+
protocol supports. When generating a request, clients SHOULD ignore
1226+
schemas for headers that are not relevant to that request.
1227+
</t>
1228+
<section title='"headerSchema" for HTTP'>
1229+
<t>
1230+
Schemas SHOULD be written to describe JSON serializations that
1231+
follow guidelines established by the work in progress
1232+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>
1233+
Approaches shown in that document's examples SHOULD be applied to
1234+
other similarly structured headers wherever possible.
1235+
</t>
1236+
<t>
1237+
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1238+
is a good candidate for description in "headerSchema". It defines
1239+
several standard values and allows for extension values.
1240+
</t>
1241+
<figure>
1242+
<preamble>
1243+
This schema indicates that the target understands the
1244+
"respond-async" preference, the "wait" preference which
1245+
takes a number of seconds to wait, as well as "minimal" and
1246+
"representation" for the "return" preference.
1247+
</preamble>
1248+
<artwork>
1249+
<![CDATA[{
1250+
"type": "object",
1251+
"properties": {
1252+
"prefer": {
1253+
"type": "array",
1254+
"items": {
1255+
"oneOf": [
1256+
{"const": "respond-async"},
1257+
{
1258+
"type": "object",
1259+
"minProperties": 1,
1260+
"maxProperties": 1,
1261+
"properties": {
1262+
{
1263+
"return": {
1264+
"enum": [
1265+
"representation",
1266+
"minimal"
1267+
]
1268+
},
1269+
"wait": {
1270+
"type": "integer",
1271+
"minimum": 1
1272+
}
1273+
}
1274+
}
1275+
}
1276+
]
1277+
},
1278+
"uniqueItems": true
1279+
}
1280+
}
1281+
}]]>
1282+
</artwork>
1283+
<postamble>
1284+
Each name/value preference pair is a single value of the
1285+
header, so each object in the list can only have one such
1286+
pair. Simplifying the "response-async" value to a single string
1287+
is based on the "Accept-Encoding" example in
1288+
<xref target="I-D.reschke-http-jfv">appendix A.4 of the JSON encoding draft</xref>.
1289+
</postamble>
1290+
</figure>
1291+
<t>
1292+
The Prefer header also stretches the limits of existing recommendations
1293+
for serializing HTTP headers in JSON. It is possible for both the
1294+
single string and name/value pair preferences to take additional
1295+
name/value parameters. While a single-string preference can accomodate
1296+
such parameters following the "Accept-Encoding" example, there is
1297+
no example to date of a name/value pair with parameters.
1298+
<cref>
1299+
We hope to get feedback from hyper-schema authors on what
1300+
practical concerns arise, and from there decide how best to
1301+
handle them. The specification for this keyword is expected to
1302+
become more well-defined in future drafts.
1303+
</cref>
1304+
</t>
1305+
</section>
1306+
</section>
1307+
11901308
<section title="submissionEncType" anchor="submissionEncType">
11911309
<t>
11921310
If present, this property indicates the media type format the
@@ -1310,6 +1428,7 @@ GET /foo/
13101428
&rfc5789;
13111429
&rfc5988;
13121430
&rfc7231;
1431+
&rfc7240;
13131432
</references>
13141433

13151434
<section title="Acknowledgments">

0 commit comments

Comments
 (0)