Skip to content

Commit 7c5354e

Browse files
geraintluffgeraintluff
committed
Update spec (nits and tweaks)
1 parent 37e342b commit 7c5354e

File tree

3 files changed

+106
-90
lines changed

3 files changed

+106
-90
lines changed

‎proposals/json-schema-hypermedia.html

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@
149149
<tr><td class="header">&nbsp;</td><td class="header">G. Court</td></tr>
150150
<tr><td class="header">&nbsp;</td><td class="header">January 31, 2013</td></tr>
151151
</table></td></tr></table>
152-
<h1><br />JSON Hyper-Schema: Hypertext definitions for JSON Schema<br />json-schema-hypermedia</h1>
152+
<h1><br />JSON Hyper-Schema: Hypertext definitions for JSON Schema<br />draft-luff-json-hyper-schema-00</h1>
153153

154154
<h3>Abstract</h3>
155155

@@ -280,8 +280,8 @@ <h3>Table of Contents</h3>
280280

281281
</p>
282282
<p>
283-
This specification will use the terminology defined by the JSON Schema core
284-
specification. It is advised that readers have a copy of this specification.
283+
This specification will use the terminology defined by the <a class='info' href='#json-schema-core'>JSON Schema core
284+
specification<span> (</span><span class='info'>Galiegue, F., Zyp, K., and G. Court, &ldquo;JSON Schema: core definitions and terminology,&rdquo; 2013.</span><span>)</span></a> [json&#8209;schema&#8209;core]. It is advised that readers have a copy of this specification.
285285

286286
</p>
287287
<a name="anchor2"></a><br /><hr />
@@ -512,7 +512,7 @@ <h3>Table of Contents</h3>
512512
json-pointer fragment resolution</h3>
513513

514514
<p>
515-
The "json-pointer" fragment resolution protocol uses a <a class='info' href='#json-pointer'>JSON Pointer<span> (</span><span class='info'>Bryan, P. and K. Zyp, &ldquo;JSON Pointer,&rdquo; October&nbsp;2011.</span><span>)</span></a> [json&#8209;pointer] to resolve fragment identifiers in URIs within instance representations.
515+
The "json-pointer" fragment resolution protocol uses a <a class='info' href='#json-pointer'>JSON Pointer<span> (</span><span class='info'>Bryan, P., Zyp, K., and M. Nottingham, &ldquo;JSON Pointer,&rdquo; August&nbsp;2012.</span><span>)</span></a> [json&#8209;pointer] to resolve fragment identifiers in URIs within instance representations.
516516

517517
</p>
518518
<a name="anchor10"></a><br /><hr />
@@ -905,7 +905,7 @@ <h3>Table of Contents</h3>
905905

906906
</p>
907907
<p>
908-
The following relations are applicable for schemas (the schema as the "from" resource in the relation):
908+
The following relations are applicable for schemas (the schema as the "from" resource in the relation) if they require no parameterization with data from the instance:
909909

910910
</p>
911911
<blockquote class="text"><dl>
@@ -921,8 +921,6 @@ <h3>Table of Contents</h3>
921921

922922
</dd>
923923
</dl></blockquote><p>
924-
925-
Links defined in the schema using these relation values SHOULD not require parameterization with data from the instance, as they describe a link for the schema, not the instances.
926924

927925
</p>
928926
<p>For example, if a schema is defined:
@@ -1120,9 +1118,14 @@ <h3>Table of Contents</h3>
11201118
"name": "Jason",
11211119
"id": 8
11221120
},
1123-
"message": "It's easy, you just add some HTML like this: &lt;script&gt;doSomethingEvil()&lt;/script&gt;"
1121+
"message": "It's easy, you just add some HTML like
1122+
this: &lt;script&gt;doSomethingEvil()&lt;/script&gt;"
11241123
}
11251124
</pre></div>
1125+
<p>
1126+
The message string was split over two lines for readability.
1127+
1128+
</p>
11261129

11271130

11281131
<p>
@@ -1351,7 +1354,9 @@ <h3>7.1.&nbsp;Normative References</h3>
13511354
<tr><td class="author-text" valign="top"><a name="RFC6570">[RFC6570]</a></td>
13521355
<td class="author-text">Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, &ldquo;<a href="http://tools.ietf.org/html/rfc6570">URI Template</a>,&rdquo; RFC&nbsp;6570, March&nbsp;2012 (<a href="http://www.rfc-editor.org/rfc/rfc6570.txt">TXT</a>).</td></tr>
13531356
<tr><td class="author-text" valign="top"><a name="json-pointer">[json-pointer]</a></td>
1354-
<td class="author-text">Bryan, P. and K. Zyp, &ldquo;<a href="http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02">JSON Pointer</a>,&rdquo; October&nbsp;2011.</td></tr>
1357+
<td class="author-text">Bryan, P., Zyp, K., and M. Nottingham, &ldquo;<a href="http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-03">JSON Pointer</a>,&rdquo; August&nbsp;2012.</td></tr>
1358+
<tr><td class="author-text" valign="top"><a name="json-schema-core">[json-schema-core]</a></td>
1359+
<td class="author-text">Galiegue, F., Zyp, K., and G. Court, &ldquo;<a href="http://tools.ietf.org/html/draft-zyp-json-schema-04">JSON Schema: core definitions and terminology</a>,&rdquo; 2013.</td></tr>
13551360
</table>
13561361

13571362
<a name="rfc.references2"></a><br /><hr />
@@ -1360,8 +1365,6 @@ <h3>7.2.&nbsp;Informative References</h3>
13601365
<table width="99%" border="0">
13611366
<tr><td class="author-text" valign="top"><a name="RFC2616">[RFC2616]</a></td>
13621367
<td class="author-text"><a href="mailto:[email protected]">Fielding, R.</a>, <a href="mailto:[email protected]">Gettys, J.</a>, <a href="mailto:[email protected]">Mogul, J.</a>, <a href="mailto:[email protected]">Frystyk, H.</a>, <a href="mailto:[email protected]">Masinter, L.</a>, <a href="mailto:[email protected]">Leach, P.</a>, and <a href="mailto:[email protected]">T. Berners-Lee</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</a>,&rdquo; RFC&nbsp;2616, June&nbsp;1999 (<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">TXT</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.ps">PS</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.pdf">PDF</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2616.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2616.xml">XML</a>).</td></tr>
1363-
<tr><td class="author-text" valign="top"><a name="RFC4627">[RFC4627]</a></td>
1364-
<td class="author-text">Crockford, D., &ldquo;<a href="http://tools.ietf.org/html/rfc4627">The application/json Media Type for JavaScript Object Notation (JSON)</a>,&rdquo; RFC&nbsp;4627, July&nbsp;2006 (<a href="http://www.rfc-editor.org/rfc/rfc4627.txt">TXT</a>).</td></tr>
13651368
<tr><td class="author-text" valign="top"><a name="RFC5226">[RFC5226]</a></td>
13661369
<td class="author-text">Narten, T. and H. Alvestrand, &ldquo;<a href="http://tools.ietf.org/html/rfc5226">Guidelines for Writing an IANA Considerations Section in RFCs</a>,&rdquo; BCP&nbsp;26, RFC&nbsp;5226, May&nbsp;2008 (<a href="http://www.rfc-editor.org/rfc/rfc5226.txt">TXT</a>).</td></tr>
13671370
<tr><td class="author-text" valign="top"><a name="RFC2046">[RFC2046]</a></td>
@@ -1392,16 +1395,13 @@ <h3>7.2.&nbsp;Informative References</h3>
13921395
</li>
13931396
<li>Split hyper-schema definition out from main schema.
13941397
</li>
1395-
<li>Removed "readonly"
1396-
</li>
1397-
<li>Capitalised the T in "encType"
1398+
<li>Capitalised the T in "encType", and the O in "readOnly"
13981399
</li>
13991400
<li>Moved "mediaType" and "contentEncoding" to the new "media" property (renamed "type" and "binaryEncoding")
14001401
</li>
14011402
<li>Added "mediaType" property to LDOs
14021403
</li>
1403-
<li>Replaced "slash-delimited" fragment resolution with
1404-
"json-pointer".
1404+
<li>Replaced "slash-delimited" fragment resolution with "json-pointer".
14051405
</li>
14061406
<li>Added "template" LDO attribute.
14071407
</li>

‎proposals/json-schema-hypermedia.txt

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Expires: August 4, 2013 SitePen (USA)
1010

1111

1212
JSON Hyper-Schema: Hypertext definitions for JSON Schema
13-
json-schema-hypermedia
13+
draft-luff-json-hyper-schema-00
1414

1515
Abstract
1616

@@ -123,8 +123,8 @@ Internet-Draft JSON Hyper-Schema January 2013
123123
uses these keywords.
124124

125125
This specification will use the terminology defined by the JSON
126-
Schema core specification. It is advised that readers have a copy of
127-
this specification.
126+
Schema core specification [json-schema-core]. It is advised that
127+
readers have a copy of this specification.
128128

129129
2. Conventions and Terminology
130130

@@ -819,7 +819,8 @@ Internet-Draft JSON Hyper-Schema January 2013
819819
the instance document, otherwise the link MUST be ignored.
820820

821821
The following relations are applicable for schemas (the schema as the
822-
"from" resource in the relation):
822+
"from" resource in the relation) if they require no parameterization
823+
with data from the instance:
823824

824825
instances This indicates the target resource that represents a
825826
collection of instances of a schema.
@@ -828,9 +829,8 @@ Internet-Draft JSON Hyper-Schema January 2013
828829
a schema. This link definition SHOULD be a submission link with a
829830
non-safe method (like POST).
830831

831-
Links defined in the schema using these relation values SHOULD not
832-
require parameterization with data from the instance, as they
833-
describe a link for the schema, not the instances.
832+
833+
834834

835835

836836

@@ -1023,23 +1023,48 @@ Internet-Draft JSON Hyper-Schema January 2013
10231023
that conversation, with a URI of:
10241024
http://forum.example.com/topics/152/comments/13
10251025

1026-
{
1027-
"topicId": 152,
1028-
"commentId": 13,
1029-
"from": {
1030-
"name": "Jane",
1031-
"id": 5
1032-
},
1033-
"to": {
1034-
"name": "Jason",
1035-
"id": 8
1036-
},
1037-
"message": "It's easy, you just add some HTML like this: <script>doSomethingEvil()</script>"
1038-
}
1026+
{
1027+
"topicId": 152,
1028+
"commentId": 13,
1029+
"from": {
1030+
"name": "Jane",
1031+
"id": 5
1032+
},
1033+
"to": {
1034+
"name": "Jason",
1035+
"id": 8
1036+
},
1037+
"message": "It's easy, you just add some HTML like
1038+
this: <script>doSomethingEvil()</script>"
1039+
}
1040+
1041+
The message string was split over two lines for readability.
10391042

10401043
A third party might then write provide the following Link Description
10411044
Object at another ___location:
10421045

1046+
1047+
1048+
1049+
1050+
1051+
1052+
1053+
1054+
1055+
1056+
1057+
1058+
1059+
1060+
1061+
1062+
1063+
Luff, et al. Expires August 4, 2013 [Page 19]
1064+
1065+
Internet-Draft JSON Hyper-Schema January 2013
1066+
1067+
10431068
{
10441069
"rel": "evil-attack",
10451070
"href": "http://forum.example.com/topics/152/comments/13",
@@ -1057,14 +1082,6 @@ Internet-Draft JSON Hyper-Schema January 2013
10571082

10581083
If the client used this "targetSchema" value when interpreting the
10591084
above data, then it might display the contents of "message" as HTML.
1060-
1061-
1062-
1063-
Luff, et al. Expires August 4, 2013 [Page 19]
1064-
1065-
Internet-Draft JSON Hyper-Schema January 2013
1066-
1067-
10681085
At this point, the JavaScript embedded in the message might be
10691086
executed (in the context of the "forum.example.com" ___domain).
10701087

@@ -1097,23 +1114,6 @@ Internet-Draft JSON Hyper-Schema January 2013
10971114

10981115

10991116

1100-
1101-
1102-
1103-
1104-
1105-
1106-
1107-
1108-
1109-
1110-
1111-
1112-
1113-
1114-
1115-
1116-
11171117

11181118

11191119
Luff, et al. Expires August 4, 2013 [Page 20]
@@ -1318,9 +1318,16 @@ Internet-Draft JSON Hyper-Schema January 2013
13181318
Nottingham, M., and D. Orchard, "URI
13191319
Template", RFC 6570, March 2012.
13201320

1321-
[json-pointer] Bryan, P. and K. Zyp, "JSON Pointer",
1322-
October 2011, <http://tools.ietf.org/
1323-
html/draft-pbryan-zyp-json-pointer-02>.
1321+
[json-pointer] Bryan, P., Zyp, K., and M. Nottingham,
1322+
"JSON Pointer", August 2012, <http://
1323+
tools.ietf.org/html/
1324+
draft-ietf-appsawg-json-pointer-03>.
1325+
1326+
[json-schema-core] Galiegue, F., Zyp, K., and G. Court,
1327+
"JSON Schema: core definitions and
1328+
terminology", 2013, <http://
1329+
tools.ietf.org/html/
1330+
draft-zyp-json-schema-04>.
13241331

13251332
7.2. Informative References
13261333

@@ -1330,13 +1337,6 @@ Internet-Draft JSON Hyper-Schema January 2013
13301337
Protocol -- HTTP/1.1", RFC 2616,
13311338
June 1999.
13321339

1333-
[RFC4627] Crockford, D., "The application/json
1334-
Media Type for JavaScript Object Notation
1335-
(JSON)", RFC 4627, July 2006.
1336-
1337-
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines
1338-
for Writing an IANA Considerations
1339-
Section in RFCs", BCP 26, RFC 5226,
13401340

13411341

13421342

@@ -1345,6 +1345,9 @@ Luff, et al. Expires August 4, 2013 [Page 24]
13451345
Internet-Draft JSON Hyper-Schema January 2013
13461346

13471347

1348+
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines
1349+
for Writing an IANA Considerations
1350+
Section in RFCs", BCP 26, RFC 5226,
13481351
May 2008.
13491352

13501353
[RFC2046] Freed, N. and N. Borenstein,
@@ -1374,9 +1377,7 @@ Appendix A. Change Log
13741377

13751378
* Split hyper-schema definition out from main schema.
13761379

1377-
* Removed "readonly"
1378-
1379-
* Capitalised the T in "encType"
1380+
* Capitalised the T in "encType", and the O in "readOnly"
13801381

13811382
* Moved "mediaType" and "contentEncoding" to the new "media"
13821383
property (renamed "type" and "binaryEncoding")
@@ -1395,7 +1396,6 @@ Appendix A. Change Log
13951396

13961397

13971398

1398-
13991399
Luff, et al. Expires August 4, 2013 [Page 25]
14001400

14011401
Internet-Draft JSON Hyper-Schema January 2013

0 commit comments

Comments
 (0)