Skip to content

Commit 4a8dc8e

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 a560f8b commit 4a8dc8e

File tree

2 files changed

+125
-0
lines changed

2 files changed

+125
-0
lines changed

‎hyper-schema.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@
4141
"description": "media type (as defined by RFC 2046) describing the link target",
4242
"type": "string"
4343
},
44+
"headerSchema": {
45+
"description": "Schema for protocol-specific headers or analogous data, as signified by URI scheme",
46+
"allOf": [ { "$ref": "#" } ]
47+
},
4448
"submissionEncType": {
4549
"description": "The media type in which to submit data along with the request",
4650
"type": "string",

‎jsonschema-hyperschema.xml

Lines changed: 121 additions & 0 deletions
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"?>
@@ -1095,6 +1097,123 @@ GET /foo/
10951097
</section>
10961098
</section>
10971099

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

12211342
<section title="Acknowledgments">

0 commit comments

Comments
 (0)