Skip to content

Commit eb9682f

Browse files
handrewshandrews
authored
Merge pull request #390 from handrews/header
Add "headerSchema"
2 parents 88747a0 + 6a496cf commit eb9682f

File tree

2 files changed

+124
-0
lines changed

2 files changed

+124
-0
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 119 additions & 0 deletions
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
]>
@@ -1305,6 +1306,123 @@ GET /foo/
13051306
</section>
13061307
</section>
13071308

1309+
<section title="headerSchema" anchor="headerSchema">
1310+
<t>
1311+
<cref>
1312+
As with "targetHints", this keyword is somewhat under-specified
1313+
to encourage experimentation and feedback as we try to balance
1314+
flexibility and clarity.
1315+
</cref>
1316+
</t>
1317+
<t>
1318+
If present, this property is a schema for protocol-specific request
1319+
headers or analogous control and meta-data. The value of this
1320+
object MUST be a valid JSON Schema.
1321+
The protocol is determined by the "href" URI scheme, although note that
1322+
resources are not guaranteed to be accessible over such a protocol.
1323+
The schema is advisory only; the target resource's behavior is not
1324+
constrained by its presence.
1325+
</t>
1326+
<t>
1327+
The purpose of this keyword is to advertise target resource interaction
1328+
features, and indicate to clients what headers and header values are
1329+
likely to be useful. Clients MAY use the schema to validate relevant
1330+
headers, but MUST NOT assume that missing headers or values are forbidden
1331+
from use. While schema authors MAY set "additionalProperties" to
1332+
false, this is NOT RECOMMENDED and MUST NOT prevent clients or user agents
1333+
from supplying additional headers when requests are made.
1334+
</t>
1335+
<t>
1336+
The exact mapping of the JSON data model into the headers is
1337+
protocol-dependent. However, in most cases this schema SHOULD
1338+
specify a type of "object", and the property names SHOULD be
1339+
lower-cased forms of the control data field names.
1340+
</t>
1341+
<t>
1342+
"headerSchema" is applicable to any request method or command that the
1343+
protocol supports. When generating a request, clients SHOULD ignore
1344+
schemas for headers that are not relevant to that request.
1345+
</t>
1346+
<section title='"headerSchema" for HTTP'>
1347+
<t>
1348+
Schemas SHOULD be written to describe JSON serializations that
1349+
follow guidelines established by the work in progress
1350+
<xref target="I-D.reschke-http-jfv">"A JSON Encoding for HTTP Header Field Values"</xref>
1351+
Approaches shown in that document's examples SHOULD be applied to
1352+
other similarly structured headers wherever possible.
1353+
</t>
1354+
<t>
1355+
The "Prefer" header defined in <xref target="RFC7240">RFC 7240</xref>
1356+
is a good candidate for description in "headerSchema". It defines
1357+
several standard values and allows for extension values.
1358+
</t>
1359+
<figure>
1360+
<preamble>
1361+
This schema indicates that the target understands the
1362+
"respond-async" preference, the "wait" preference which
1363+
takes a number of seconds to wait, as well as "minimal" and
1364+
"representation" for the "return" preference.
1365+
</preamble>
1366+
<artwork>
1367+
<![CDATA[{
1368+
"type": "object",
1369+
"properties": {
1370+
"prefer": {
1371+
"type": "array",
1372+
"items": {
1373+
"oneOf": [
1374+
{"const": "respond-async"},
1375+
{
1376+
"type": "object",
1377+
"minProperties": 1,
1378+
"maxProperties": 1,
1379+
"properties": {
1380+
{
1381+
"return": {
1382+
"enum": [
1383+
"representation",
1384+
"minimal"
1385+
]
1386+
},
1387+
"wait": {
1388+
"type": "integer",
1389+
"minimum": 1
1390+
}
1391+
}
1392+
}
1393+
}
1394+
]
1395+
},
1396+
"uniqueItems": true
1397+
}
1398+
}
1399+
}]]>
1400+
</artwork>
1401+
<postamble>
1402+
Each name/value preference pair is a single value of the
1403+
header, so each object in the list can only have one such
1404+
pair. Simplifying the "response-async" value to a single string
1405+
is based on the "Accept-Encoding" example in
1406+
<xref target="I-D.reschke-http-jfv">appendix A.4 of the JSON encoding draft</xref>.
1407+
</postamble>
1408+
</figure>
1409+
<t>
1410+
The Prefer header also stretches the limits of existing recommendations
1411+
for serializing HTTP headers in JSON. It is possible for both the
1412+
single string and name/value pair preferences to take additional
1413+
name/value parameters. While a single-string preference can accomodate
1414+
such parameters following the "Accept-Encoding" example, there is
1415+
no example to date of a name/value pair with parameters.
1416+
<cref>
1417+
We hope to get feedback from hyper-schema authors on what
1418+
practical concerns arise, and from there decide how best to
1419+
handle them. The specification for this keyword is expected to
1420+
become more well-defined in future drafts.
1421+
</cref>
1422+
</t>
1423+
</section>
1424+
</section>
1425+
13081426
<section title="submissionEncType" anchor="submissionEncType">
13091427
<t>
13101428
If present, this property indicates the media type format the
@@ -1428,6 +1546,7 @@ GET /foo/
14281546
&rfc5789;
14291547
&rfc5988;
14301548
&rfc7231;
1549+
&rfc7240;
14311550
</references>
14321551

14331552
<section title="Acknowledgments">

‎links.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,11 @@
5353
"mediaType": {
5454
"type": "string"
5555
},
56+
"headerSchema": {
57+
"allOf": [
58+
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
59+
]
60+
},
5661
"submissionEncType": {
5762
"type": "string",
5863
"default": "application/json"

0 commit comments

Comments
 (0)