Skip to content

Commit 84d28d6

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 1d8963e commit 84d28d6

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
@@ -9,6 +9,7 @@
99
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
1010
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
1111
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
12+
<!ENTITY rfc7240 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7240.xml">
1213
<!ENTITY I-D.reschke-http-jfv SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-reschke-http-jfv-06.xml">
1314
]>
1415
<?rfc toc="yes"?>
@@ -1097,6 +1098,123 @@ GET /foo/
10971098
</section>
10981099
</section>
10991100

1101+
<section title="headerSchema" anchor="headerSchema">
1102+
<t>
1103+
<cref>
1104+
As with "targetHints", this keyword is somewhat under-specified
1105+
to encourage experiementation and feedback as we try to balance
1106+
flexibility and clarity.
1107+
</cref>
1108+
</t>
1109+
<t>
1110+
If present, this property is a schema for protocol-specific request
1111+
headers or analogous control and meta-data. The value of this
1112+
object MUST be a valid JSON Schema.
1113+
The protocol is determined by the "href" URI scheme, although note that
1114+
resources are not guaranteed to be accessible over such a protocol.
1115+
The schema is advisory only; the target resource's behavior is not
1116+
constrained by its presence.
1117+
</t>
1118+
<t>
1119+
The purpose of this keyword is to advertise target resource interaction
1120+
features, and indicate to clients what headers and header values are
1121+
likely to be useful. Clients MAY use the schema to validate relevant
1122+
headers, but MUST NOT assume that missing headers or values are forbidden
1123+
from use. While schema authors MAY set "additionalProperties" to
1124+
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
1125+
from supplying additional headers when requests are made.
1126+
</t>
1127+
<t>
1128+
The exact mapping of the JSON data model into the headers is
1129+
protocol-dependent. However, in most cases this schema SHOULD
1130+
specify a type of "object", and the property names SHOULD be
1131+
lower-cased forms of the control data field names.
1132+
</t>
1133+
<t>
1134+
"headerSchema" is applicable to any request method or command that the
1135+
protocol supports. When generating a request, clients SHOULD ignore
1136+
schemas for headers that are not relevant to that request.
1137+
</t>
1138+
<section title='"headerSchema" for HTTP'>
1139+
<t>
1140+
Schemas SHOULD be written to describe JSON serializations that
1141+
follow guidelines established by the work in progress
1142+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>
1143+
Approaches shown in that document's examples SHOULD be applied to
1144+
other similarly structured headers wherever possible.
1145+
</t>
1146+
<t>
1147+
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1148+
is a good candidate for description in "headerSchema". It defines
1149+
several standard values and allows for extension values.
1150+
</t>
1151+
<figure>
1152+
<preamble>
1153+
This schema indicates that the target understands the
1154+
"respond-async" preference, the "wait" preference which
1155+
takes a number of seconds to wait, as well as "minimal" and
1156+
"representation" for the "return" preference.
1157+
</preamble>
1158+
<artwork>
1159+
<![CDATA[{
1160+
"type": "object",
1161+
"properties": {
1162+
"prefer": {
1163+
"type": "array",
1164+
"items": {
1165+
"oneOf": [
1166+
{"const": "respond-async"},
1167+
{
1168+
"type": "object",
1169+
"minProperties": 1,
1170+
"maxProperties": 1,
1171+
"properties": {
1172+
{
1173+
"return": {
1174+
"enum": [
1175+
"representation",
1176+
"minimal"
1177+
]
1178+
},
1179+
"wait": {
1180+
"type": "integer",
1181+
"minimum": 1
1182+
}
1183+
}
1184+
}
1185+
}
1186+
]
1187+
},
1188+
"uniqueItems": true
1189+
}
1190+
}
1191+
}]]>
1192+
</artwork>
1193+
<postamble>
1194+
Each name/value preference pair is a single value of the
1195+
header, so each object in the list can only have one such
1196+
pair. Simplifying the "response-async" value to a single string
1197+
is based on the "Accept-Encoding" example in
1198+
<xref target="I-D.reschke-http-jfv">appendix A.4 of the JSON encoding draft</xref>.
1199+
</postamble>
1200+
</figure>
1201+
<t>
1202+
The Prefer header also stretches the limits of existing recommendations
1203+
for serializing HTTP headers in JSON. It is possible for both the
1204+
single string and name/value pair preferences to take additional
1205+
name/value parameters. While a single-string preference can accomodate
1206+
such parameters following the "Accept-Encoding" example, there is
1207+
no example to date of a name/value pair with parameters.
1208+
<cref>
1209+
We hope to get feedback from hyper-schema authors on what
1210+
practical concerns arise, and from there decide how best to
1211+
handle them. The specification for this keyword is expected to
1212+
become more well-defined in future drafts.
1213+
</cref>
1214+
</t>
1215+
</section>
1216+
</section>
1217+
11001218
<section title="submissionEncType" anchor="submissionEncType">
11011219
<t>
11021220
If present, this property indicates the media type format the
@@ -1218,6 +1336,7 @@ GET /foo/
12181336
&rfc5789;
12191337
&rfc5988;
12201338
&rfc7231;
1339+
&rfc7240;
12211340
</references>
12221341

12231342
<section title="Acknowledgments">

0 commit comments

Comments
 (0)