Skip to content

Commit 917341f

Browse files
awwrightawwright
authored
Merge pull request json-schema-org#245 from handrews/fragment
Clearly define schema+json fragid forms.
2 parents 868169c + 297720e commit 917341f

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.
@@ -352,7 +387,7 @@
352387
</t>
353388
</section>
354389

355-
<section title='The "$id" keyword'>
390+
<section title='The "$id" keyword' anchor="id-keyword">
356391
<t>
357392
The "$id" keyword defines a URI for the schema,
358393
and the base URI that other URI references within the schema are resolved against.
@@ -363,15 +398,26 @@
363398
This value SHOULD be normalized, and SHOULD NOT be an empty fragment &lt;#&gt; or an empty string &lt;&gt;.
364399
</t>
365400
<t>
366-
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with an absolute-URI (containing a scheme, but no fragment).
401+
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
402+
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
403+
have one that is an empty string.
404+
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
405+
<cref>
406+
How should an "$id" URI reference containing a fragement with other components
407+
be interpreted? There are two cases: when the other components match
408+
the current base URI and when they change the base URI.
409+
</cref>
367410
</t>
368411
<t>
369412
To name subschemas in a JSON Schema document,
370413
subschemas can use "$id" to give themselves a document-local identifier.
371-
This form of "$id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference,
372-
followed by a letter ([A-Za-z]), followed by any number of
373-
letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods (".").
374-
<!-- This restriction is the same one defined by XML -->
414+
This is done by setting "$id" to a URI reference consisting only of a fragment.
415+
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
416+
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods (".").
417+
</t>
418+
<t>
419+
The effect of defining an "$id" that neither matches the above
420+
requirements nor is a valid JSON pointer is not defined.
375421
</t>
376422
<t>
377423
For example:
@@ -401,7 +447,8 @@
401447
<t>
402448
The schemas at the following URI-encoded <xref target="RFC6901">JSON
403449
Pointers</xref> (relative to the root schema) have the following
404-
base URIs, and are identifiable by either URI:
450+
base URIs, and are identifiable by either URI in accordance with
451+
Section <xref target="fragments" format="counter"></xref> above:
405452
</t>
406453
<t>
407454
<list style="hanging">
@@ -502,7 +549,7 @@ Link: <http://example.com/my-hyper-schema#>; rel="describedby"
502549
</section>
503550

504551

505-
<section title='Describing a profile of JSON'>
552+
<section title='Describing a profile of JSON' anchor="profile">
506553
<t>
507554
Instances MAY specify a "profile" as described in <xref target="RFC6906">The 'profile' Link Relation</xref>.
508555
When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile.
@@ -581,7 +628,7 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
581628

582629
</section>
583630

584-
<section title="Security considerations">
631+
<section title="Security considerations" anchor="security">
585632
<t>
586633
Both schemas and instances are JSON values. As such, all security considerations
587634
defined in <xref target="RFC7159">RFC 7159</xref> apply.
@@ -604,8 +651,27 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
604651
The proposed MIME media type for JSON Schema is defined as follows:
605652

606653
<list>
607-
<t>type name: application;</t>
608-
<t>subtype name: schema+json.</t>
654+
<t>Type name: application</t>
655+
<t>Subtype name: schema+json</t>
656+
<t>Required parameters: N/A</t>
657+
<t>
658+
Encoding considerations: Encoding considerations are
659+
identical to those specified for the "application/json"
660+
media type. See <xref target="RFC7159">JSON</xref>.
661+
</t>
662+
<t>
663+
Security considerations: See Section
664+
<xref target="security" format="counter"></xref> above.
665+
</t>
666+
<t>
667+
Interoperability considerations: See Sections
668+
<xref target="language" format="counter"></xref> and
669+
<xref target="integers" format="counter"></xref> above.
670+
</t>
671+
<t>
672+
Fragment identifier considerations: See Section
673+
<xref target="fragments" format="counter"></xref>
674+
</t>
609675
</list>
610676
</t>
611677

@@ -617,16 +683,18 @@ User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0
617683
<references title="Normative References">
618684
&RFC2119;
619685
&RFC3986;
686+
&RFC6839;
687+
&RFC6901;
620688
&RFC7159;
621689
&ldp;
622690
</references>
623691

624692
<references title="Informative References">
625693
&RFC5988;
626-
&RFC6901;
627694
&RFC6906;
628695
&RFC7049;
629696
&RFC7231;
697+
&fragid-best-practices;
630698
<reference anchor="json-schema-validation">
631699
<front>
632700
<title>JSON Schema Validation: A Vocabulary for Structural Validation of JSON</title>

0 commit comments

Comments
 (0)