Skip to content

Commit f64f860

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 67ff041 commit f64f860

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎jsonschema-hyperschema.xml

+121
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1111
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.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">
14+
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1315
]>
1416
<?rfc toc="yes"?>
1517
<?rfc symrefs="yes"?>
@@ -1141,6 +1143,123 @@ GET /foo/
11411143
</section>
11421144
</section>
11431145

1146+
<section title="headerSchema" anchor="headerSchema">
1147+
<t>
1148+
<cref>
1149+
As with "targetHints", this keyword is somewhat under-specified
1150+
to encourage experiementation and feedback as we try to balance
1151+
flexibility and clarity.
1152+
</cref>
1153+
</t>
1154+
<t>
1155+
If present, this property is a schema for protocol-specific request
1156+
headers or analogous control and meta-data. The value of this
1157+
object MUST be a valid JSON Schema.
1158+
The protocol is determined by the "href" URI scheme, although note that
1159+
resources are not guaranteed to be accessible over such a protocol.
1160+
The schema is advisory only; the target resource's behavior is not
1161+
constrained by its presence.
1162+
</t>
1163+
<t>
1164+
The purpose of this keyword is to advertise target resource interaction
1165+
features, and indicate to clients what headers and header values are
1166+
likely to be useful. Clients MAY use the schema to validate relevant
1167+
headers, but MUST NOT assume that missing headers or values are forbidden
1168+
from use. While schema authors MAY set "additionalProperties" to
1169+
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
1170+
from supplying additional headers when requests are made.
1171+
</t>
1172+
<t>
1173+
The exact mapping of the JSON data model into the headers is
1174+
protocol-dependent. However, in most cases this schema SHOULD
1175+
specify a type of "object", and the property names SHOULD be
1176+
lower-cased forms of the control data field names.
1177+
</t>
1178+
<t>
1179+
"headerSchema" is applicable to any request method or command that the
1180+
protocol supports. When generating a request, clients SHOULD ignore
1181+
schemas for headers that are not relevant to that request.
1182+
</t>
1183+
<section title='"headerSchema" for HTTP'>
1184+
<t>
1185+
Schemas SHOULD be written to describe JSON serializations that
1186+
follow guidelines established by the work in progress
1187+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>
1188+
Approaches shown in that document's examples SHOULD be applied to
1189+
other similarly structured headers wherever possible.
1190+
</t>
1191+
<t>
1192+
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1193+
is a good candidate for description in "headerSchema". It defines
1194+
several standard values and allows for extension values.
1195+
</t>
1196+
<figure>
1197+
<preamble>
1198+
This schema indicates that the target understands the
1199+
"respond-async" preference, the "wait" preference which
1200+
takes a number of seconds to wait, as well as "minimal" and
1201+
"representation" for the "return" preference.
1202+
</preamble>
1203+
<artwork>
1204+
<![CDATA[{
1205+
"type": "object",
1206+
"properties": {
1207+
"prefer": {
1208+
"type": "array",
1209+
"items": {
1210+
"oneOf": [
1211+
{"const": "respond-async"},
1212+
{
1213+
"type": "object",
1214+
"minProperties": 1,
1215+
"maxProperties": 1,
1216+
"properties": {
1217+
{
1218+
"return": {
1219+
"enum": [
1220+
"representation",
1221+
"minimal"
1222+
]
1223+
},
1224+
"wait": {
1225+
"type": "integer",
1226+
"minimum": 1
1227+
}
1228+
}
1229+
}
1230+
}
1231+
]
1232+
},
1233+
"uniqueItems": true
1234+
}
1235+
}
1236+
}]]>
1237+
</artwork>
1238+
<postamble>
1239+
Each name/value preference pair is a single value of the
1240+
header, so each object in the list can only have one such
1241+
pair. Simplifying the "response-async" value to a single string
1242+
is based on the "Accept-Encoding" example in
1243+
<xref target="I-D.reschke-http-jfv">appendix A.4 of the JSON encoding draft</xref>.
1244+
</postamble>
1245+
</figure>
1246+
<t>
1247+
The Prefer header also stretches the limits of existing recommendations
1248+
for serializing HTTP headers in JSON. It is possible for both the
1249+
single string and name/value pair preferences to take additional
1250+
name/value parameters. While a single-string preference can accomodate
1251+
such parameters following the "Accept-Encoding" example, there is
1252+
no example to date of a name/value pair with parameters.
1253+
<cref>
1254+
We hope to get feedback from hyper-schema authors on what
1255+
practical concerns arise, and from there decide how best to
1256+
handle them. The specification for this keyword is expected to
1257+
become more well-defined in future drafts.
1258+
</cref>
1259+
</t>
1260+
</section>
1261+
</section>
1262+
11441263
<section title="submissionEncType" anchor="submissionEncType">
11451264
<t>
11461265
If present, this property indicates the media type format the
@@ -1262,6 +1381,8 @@ GET /foo/
12621381
&rfc5789;
12631382
&rfc5988;
12641383
&rfc7231;
1384+
&rfc7240;
1385+
&I-D.reschke-http-jfv;
12651386
</references>
12661387

12671388
<section title="Acknowledgments">

0 commit comments

Comments
 (0)