Skip to content

Commit f9bfc36

Browse files
handrewshandrews
committed
Clearly define schema+json fragid forms.
Reference the JSON Pointer RFC for using JSON Pointers as fragids (includes encoding requirements). Remove the syntax description for how to write a fragment URI reference (leading "#") as that is covered by RFC 3986. Define legal plain name fragments as any that do not conflict with JSON Pointer fragments. The previous rules from XML, or rules from HTML5, could be considered as well, but it's not clear what benefit there is for the restrictions. Also fill in a bit more of the IANA considerations section.
1 parent f7bb080 commit f9bfc36

File tree

1 file changed

+82
-14
lines changed

1 file changed

+82
-14
lines changed

‎jsonschema-core.xml‎

Lines changed: 82 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@
33
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
44
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
55
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
6+
<!ENTITY RFC6839 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6839.xml">
67
<!ENTITY RFC6901 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6901.xml">
78
<!ENTITY RFC6906 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6906.xml">
89
<!ENTITY RFC7049 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7049.xml">
910
<!ENTITY RFC7159 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7159.xml">
1011
<!ENTITY RFC7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
1112
<!ENTITY ldp SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/reference.W3C.REC-ldp-20150226.xml">
13+
<!ENTITY fragid-best-practices SYSTEM "https://xml2rfc.tools.ietf.org/public/rfc/bibxml4/reference.W3C.WD-fragid-best-practices-20121025.xml">
1214
]>
1315
<?rfc toc="yes"?>
1416
<?rfc symrefs="yes"?>
@@ -251,6 +253,39 @@
251253

252254
</section>
253255

256+
<section title="Fragment identifiers" anchor="fragments">
257+
<t>
258+
In accordance with section 3.1 of <xref target="RFC6839"></xref>,
259+
the syntax and semantics of fragment identifiers specified for
260+
any +json media type SHOULD be as specified for "application/json".
261+
(At publication of this document, there is no fragment identification
262+
syntax defined for "application/json".)
263+
</t>
264+
<t>
265+
Additionally, the "application/schema+json" media type supports two
266+
fragment identifier structures: plain names and JSON Pointers.
267+
The use of JSON Pointers as URI fragment identifiers is described in
268+
<xref target="RFC6901">RFC 6901</xref>.
269+
Fragment identifiers matching the JSON Pointer syntax, including
270+
the empty string, MUST be interpreted as JSON Pointer fragment
271+
identifiers.
272+
</t>
273+
<t>
274+
Per the W3C's
275+
<xref target="W3C.WD-fragid-best-practices-20121025">best practices for fragment identifiers</xref>,
276+
plain name fragment identifiers are reserved for referencing
277+
locally named schemas. All fragment identifiers that do
278+
not match the JSON Pointer syntax MUST be interpreted as
279+
plain name fragment identifiers.
280+
</t>
281+
<t>
282+
Defining and referencing a plain name fragment identifier
283+
in the <xref target="id-keyword">"$id" keyword</xref> section.
284+
</t>
285+
<t>
286+
</t>
287+
</section>
288+
254289
<section title="General considerations">
255290

256291
<section title="Range of JSON values">
@@ -260,15 +295,15 @@
260295
</t>
261296
</section>
262297

263-
<section title="Programming language independence">
298+
<section title="Programming language independence" anchor="language">
264299
<t>
265300
JSON Schema is programming language agnostic, and supports the full range of values described in the data model.
266301
Be aware, however, that some languages and JSON parsers may not be able to represent in memory
267302
the full range of values describable by JSON.
268303
</t>
269304
</section>
270305

271-
<section title="Mathematical integers">
306+
<section title="Mathematical integers" anchor="integers">
272307
<t>
273308
Some programming languages and parsers use different internal representations for floating
274309
point numbers than they do for integers.
@@ -346,7 +381,7 @@
346381
</t>
347382
</section>
348383

349-
<section title='The "$id" keyword'>
384+
<section title='The "$id" keyword' anchor="id-keyword">
350385
<t>
351386
The "$id" keyword defines a URI for the schema,
352387
and the base URI that other URI references within the schema are resolved against.
@@ -357,15 +392,26 @@
357392
This value SHOULD be normalized, and SHOULD NOT be an empty fragment &lt;#&gt; or an empty string &lt;&gt;.
358393
</t>
359394
<t>
360-
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with an absolute-URI (containing a scheme, but no fragment).
395+
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
396+
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
397+
have one that is an empty string.
398+
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
399+
<cref>
400+
How should an "$id" URI reference containing a fragement with other components
401+
be interpreted? There are two cases: when the other components match
402+
the current base URI and when they change the base URI.
403+
</cref>
361404
</t>
362405
<t>
363406
To name subschemas in a JSON Schema document,
364407
subschemas can use "$id" to give themselves a document-local identifier.
365-
This form of "$id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
366-
followed by a letter ([A-Za-z]), followed by any number of
367-
letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods (".").
368-
<!-- This restriction is the same one defined by XML -->
408+
This is done by setting "$id" to a URI reference consisting only of a fragment.
409+
The fragment identifier MUST NOT match the syntax of a JSON Pointer fragment
410+
identifier.
411+
</t>
412+
<t>
413+
The effect of defining an "$id" that is appears to be a JSON Pointer that does not match
414+
the expected JSON Pointer for that schema is not defined.
369415
</t>
370416
<t>
371417
For example:
@@ -395,7 +441,8 @@
395441
<t>
396442
The schemas at the following URI-encoded <xref target="RFC6901">JSON
397443
Pointers</xref> (relative to the root schema) have the following
398-
base URIs, and are identifiable by either URI:
444+
base URIs, and are identifiable by either URI in accordance with
445+
Section <xref target="fragments" format="counter"></xref> above:
399446
</t>
400447
<t>
401448
<list style="hanging">
@@ -496,7 +543,7 @@ Link: <http://example.com/my-hyper-schema#>; rel="describedby"
496543
</section>
497544

498545

499-
<section title='Describing a profile of JSON'>
546+
<section title='Describing a profile of JSON' anchor="profile">
500547
<t>
501548
Instances MAY specify a "profile" as described in <xref target="RFC6906">The 'profile' Link Relation</xref>.
502549
When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile.
@@ -575,7 +622,7 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
575622

576623
</section>
577624

578-
<section title="Security considerations">
625+
<section title="Security considerations" anchor="security">
579626
<t>
580627
Both schemas and instances are JSON values. As such, all security considerations
581628
defined in <xref target="RFC7159">RFC 7159</xref> apply.
@@ -598,8 +645,27 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
598645
The proposed MIME media type for JSON Schema is defined as follows:
599646

600647
<list>
601-
<t>type name: application;</t>
602-
<t>subtype name: schema+json.</t>
648+
<t>Type name: application</t>
649+
<t>Subtype name: schema+json</t>
650+
<t>Required parameters: N/A</t>
651+
<t>
652+
Encoding considerations: Encoding considerations are
653+
identical to those specified for the "application/json"
654+
media type. See <xref target="RFC7159">JSON</xref>.
655+
</t>
656+
<t>
657+
Security considerations: See Section
658+
<xref target="security" format="counter"></xref> above.
659+
</t>
660+
<t>
661+
Interoperability considerations: See Sections
662+
<xref target="language" format="counter"></xref> and
663+
<xref target="integers" format="counter"></xref> above.
664+
</t>
665+
<t>
666+
Fragment identifier considerations: See Section
667+
<xref target="fragments" format="counter"></xref>
668+
</t>
603669
</list>
604670
</t>
605671

@@ -611,16 +677,18 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
611677
<references title="Normative References">
612678
&RFC2119;
613679
&RFC3986;
680+
&RFC6839;
681+
&RFC6901;
614682
&RFC7159;
615683
&ldp;
616684
</references>
617685

618686
<references title="Informative References">
619687
&RFC5988;
620-
&RFC6901;
621688
&RFC6906;
622689
&RFC7049;
623690
&RFC7231;
691+
&fragid-best-practices;
624692
<reference anchor="json-schema-validation">
625693
<front>
626694
<title>JSON Schema Validation: A Vocabulary for Structural Validation of JSON</title>

0 commit comments

Comments
 (0)