Skip to content

Commit e79dfd0

Browse files
handrewshandrews
committed
Move HTTP up between Implementation and Examples
While it is technically not a primary part of the specification, but rather an application of the spec to a specific protocol, it is important enough to explaining the motivation and usage of Hyper-Schema to discuss immediately after the general implementation requirements but before the examples. This allows the examples to reference and illustrate HTTP usage.
1 parent 102cf9a commit e79dfd0

File tree

1 file changed

+127
-126
lines changed

1 file changed

+127
-126
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 127 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1222,132 +1222,6 @@ for varname in templateData:
12221222
</section>
12231223
</section>
12241224

1225-
<section title="Examples" anchor="examples">
1226-
<t><cref>Examples are being added in a subsequent PR.</cref></t>
1227-
</section>
1228-
1229-
<section title="Security Considerations" anchor="security">
1230-
<t><cref>Need to reference the core and validation security considerations.</cref></t>
1231-
<section title='"self" links'>
1232-
<t>
1233-
When link relation of "self" is used to denote a full representation of an
1234-
object, the user agent SHOULD NOT consider the representation to be the
1235-
authoritative representation of the resource denoted by the target URI if
1236-
the target URI is not equivalent to or a sub-path of the URI used to request
1237-
the resource representation which contains the target URI with the "self"
1238-
link.
1239-
</t>
1240-
</section>
1241-
<section title="Target attributes">
1242-
<t>
1243-
<cref>
1244-
This whole section needs more work, but I do like having security
1245-
concerns around target interactions consolidated and addressed as a whole.
1246-
</cref>
1247-
</t>
1248-
<t>
1249-
The "targetMediaType" property in link definitions defines the expected
1250-
format of the link's target.
1251-
However, this is advisory only, and MUST NOT be considered authoritative.
1252-
</t>
1253-
<t>
1254-
When choosing how to interpret data, the type information provided by the
1255-
server (or inferred from the filename, or any other usual method) MUST be
1256-
the only consideration, and the "targetMediaType" property of the link
1257-
MUST NOT be used.
1258-
User agents MAY use this information to determine how they represent the
1259-
link or where to display it (for example hover-text, opening in a new tab).
1260-
If user agents decide to pass the link to an external program, they SHOULD
1261-
first verify that the data is of a type that would normally be passed to
1262-
that external program.
1263-
</t>
1264-
<t>
1265-
This is to guard against re-interpretation of "safe" data, similar to the
1266-
precautions for "targetSchema".
1267-
</t>
1268-
<t>
1269-
The "targetSchema" keyword has similar security concerns to that of
1270-
"targetMediaType".
1271-
Clients MUST NOT use the value of this property to aid in the interpretation
1272-
of the data received in response to following the link, as this leaves
1273-
"safe" data open to re-interpretation.
1274-
</t>
1275-
</section>
1276-
</section>
1277-
<!--
1278-
<section title="IANA Considerations">
1279-
<t>No considerations</t>
1280-
</section>
1281-
-->
1282-
<section title="Acknowledgments">
1283-
<t>
1284-
Thanks to
1285-
Gary Court,
1286-
Francis Galiegue,
1287-
Kris Zyp,
1288-
and Geraint Luff
1289-
for their work on the initial drafts of JSON Schema.
1290-
</t>
1291-
<t>
1292-
Thanks to
1293-
Jason Desrosiers,
1294-
Daniel Perrett,
1295-
Erik Wilde,
1296-
Ben Hutton,
1297-
Evgeny Poberezkin,
1298-
Brad Bowman,
1299-
Gowry Sankar,
1300-
Donald Pipowitch,
1301-
Dave Finlay,
1302-
and Denis Laxalde
1303-
for their submissions and patches to the document.
1304-
</t>
1305-
</section>
1306-
</middle>
1307-
1308-
<back>
1309-
<!-- References Section -->
1310-
<references title="Normative References">
1311-
&rfc2119;
1312-
&rfc3986;
1313-
<!--&rfc4287;-->
1314-
&rfc6570;
1315-
&rfc6901;
1316-
&I-D.luff-relative-json-pointer;
1317-
&I-D.reschke-http-jfv;
1318-
<reference anchor="json-schema">
1319-
<front>
1320-
<title>JSON Schema: A Media Type for Describing JSON Documents</title>
1321-
<author initials="A." surname="Wright">
1322-
<organization/>
1323-
</author>
1324-
<date year="2016" month="October"/>
1325-
</front>
1326-
<seriesInfo name="Internet-Draft" value="draft-wright-json-schema-01" />
1327-
</reference>
1328-
<reference anchor="json-schema-validation">
1329-
<front>
1330-
<title>JSON Schema Validation: A Vocabulary for Structural Validation of JSON</title>
1331-
<author initials="A." surname="Wright">
1332-
<organization/>
1333-
</author>
1334-
<date year="2016" month="October"/>
1335-
</front>
1336-
<seriesInfo name="Internet-Draft" value="draft-wright-json-schema-validation-01" />
1337-
</reference>
1338-
</references>
1339-
<references title="Informative References">
1340-
&rfc2046;
1341-
<!--&rfc5226;-->
1342-
&rfc4151;
1343-
&rfc5789;
1344-
&rfc5988;
1345-
&rfc6573;
1346-
&rfc7230;
1347-
&rfc7231;
1348-
&rfc7807;
1349-
&I-D.nottingham-rfc5988bis;
1350-
</references>
13511225
<section title="JSON Hyper-Schema and HTTP" anchor="HTTP">
13521226
<t>
13531227
While JSON Hyper-Schema is a hypermedia format and therefore protocol-independent,
@@ -1480,6 +1354,133 @@ for varname in templateData:
14801354
</t>
14811355
</section>
14821356
</section>
1357+
1358+
<section title="Examples" anchor="examples">
1359+
<t><cref>Examples are being added in a subsequent PR.</cref></t>
1360+
</section>
1361+
1362+
<section title="Security Considerations" anchor="security">
1363+
<t><cref>Need to reference the core and validation security considerations.</cref></t>
1364+
<section title='"self" links'>
1365+
<t>
1366+
When link relation of "self" is used to denote a full representation of an
1367+
object, the user agent SHOULD NOT consider the representation to be the
1368+
authoritative representation of the resource denoted by the target URI if
1369+
the target URI is not equivalent to or a sub-path of the URI used to request
1370+
the resource representation which contains the target URI with the "self"
1371+
link.
1372+
</t>
1373+
</section>
1374+
<section title="Target attributes">
1375+
<t>
1376+
<cref>
1377+
This whole section needs more work, but I do like having security
1378+
concerns around target interactions consolidated and addressed as a whole.
1379+
</cref>
1380+
</t>
1381+
<t>
1382+
The "targetMediaType" property in link definitions defines the expected
1383+
format of the link's target.
1384+
However, this is advisory only, and MUST NOT be considered authoritative.
1385+
</t>
1386+
<t>
1387+
When choosing how to interpret data, the type information provided by the
1388+
server (or inferred from the filename, or any other usual method) MUST be
1389+
the only consideration, and the "targetMediaType" property of the link
1390+
MUST NOT be used.
1391+
User agents MAY use this information to determine how they represent the
1392+
link or where to display it (for example hover-text, opening in a new tab).
1393+
If user agents decide to pass the link to an external program, they SHOULD
1394+
first verify that the data is of a type that would normally be passed to
1395+
that external program.
1396+
</t>
1397+
<t>
1398+
This is to guard against re-interpretation of "safe" data, similar to the
1399+
precautions for "targetSchema".
1400+
</t>
1401+
<t>
1402+
The "targetSchema" keyword has similar security concerns to that of
1403+
"targetMediaType".
1404+
Clients MUST NOT use the value of this property to aid in the interpretation
1405+
of the data received in response to following the link, as this leaves
1406+
"safe" data open to re-interpretation.
1407+
</t>
1408+
</section>
1409+
</section>
1410+
<!--
1411+
<section title="IANA Considerations">
1412+
<t>No considerations</t>
1413+
</section>
1414+
-->
1415+
<section title="Acknowledgments">
1416+
<t>
1417+
Thanks to
1418+
Gary Court,
1419+
Francis Galiegue,
1420+
Kris Zyp,
1421+
and Geraint Luff
1422+
for their work on the initial drafts of JSON Schema.
1423+
</t>
1424+
<t>
1425+
Thanks to
1426+
Jason Desrosiers,
1427+
Daniel Perrett,
1428+
Erik Wilde,
1429+
Ben Hutton,
1430+
Evgeny Poberezkin,
1431+
Brad Bowman,
1432+
Gowry Sankar,
1433+
Donald Pipowitch,
1434+
Dave Finlay,
1435+
and Denis Laxalde
1436+
for their submissions and patches to the document.
1437+
</t>
1438+
</section>
1439+
</middle>
1440+
1441+
<back>
1442+
<!-- References Section -->
1443+
<references title="Normative References">
1444+
&rfc2119;
1445+
&rfc3986;
1446+
<!--&rfc4287;-->
1447+
&rfc6570;
1448+
&rfc6901;
1449+
&I-D.luff-relative-json-pointer;
1450+
&I-D.reschke-http-jfv;
1451+
<reference anchor="json-schema">
1452+
<front>
1453+
<title>JSON Schema: A Media Type for Describing JSON Documents</title>
1454+
<author initials="A." surname="Wright">
1455+
<organization/>
1456+
</author>
1457+
<date year="2016" month="October"/>
1458+
</front>
1459+
<seriesInfo name="Internet-Draft" value="draft-wright-json-schema-01" />
1460+
</reference>
1461+
<reference anchor="json-schema-validation">
1462+
<front>
1463+
<title>JSON Schema Validation: A Vocabulary for Structural Validation of JSON</title>
1464+
<author initials="A." surname="Wright">
1465+
<organization/>
1466+
</author>
1467+
<date year="2016" month="October"/>
1468+
</front>
1469+
<seriesInfo name="Internet-Draft" value="draft-wright-json-schema-validation-01" />
1470+
</reference>
1471+
</references>
1472+
<references title="Informative References">
1473+
&rfc2046;
1474+
<!--&rfc5226;-->
1475+
&rfc4151;
1476+
&rfc5789;
1477+
&rfc5988;
1478+
&rfc6573;
1479+
&rfc7230;
1480+
&rfc7231;
1481+
&rfc7807;
1482+
&I-D.nottingham-rfc5988bis;
1483+
</references>
14831484
<section title="Using JSON Hyper-Schema in APIs" anchor="apis">
14841485
<t>
14851486
Hypermedia APIs, which follow the constraints of the REST architectural

0 commit comments

Comments
 (0)