Skip to content

Commit 0b1a062

Browse files
handrewshandrews
authored
Merge pull request #550 from handrews/ref-id
Remove internal/external reference terminology, expand use cases and examples
2 parents 677f162 + 2fa90f6 commit 0b1a062

File tree

1 file changed

+174
-97
lines changed

1 file changed

+174
-97
lines changed

‎jsonschema-core.xml

+174-97
Original file line numberDiff line numberDiff line change
@@ -527,33 +527,6 @@
527527
</t>
528528
</section>
529529

530-
<section title='Schema References With "$ref"'>
531-
<t>
532-
The "$ref" keyword is used to reference a schema, and provides the ability to
533-
validate recursive structures through self-reference.
534-
</t>
535-
<t>
536-
An object schema with a "$ref" property MUST be interpreted as a "$ref" reference.
537-
The value of the "$ref" property MUST be a URI Reference.
538-
Resolved against the current URI base, it identifies the URI of a schema to use.
539-
All other properties in a "$ref" object MUST be ignored.
540-
</t>
541-
<t>
542-
The URI is not a network locator, only an identifier. A schema need not be
543-
downloadable from the address if it is a network-addressable URL, and
544-
implementations SHOULD NOT assume they should perform a network operation when they
545-
encounter a network-addressable URI.
546-
</t>
547-
<t>
548-
A schema MUST NOT be run into an infinite loop against a schema. For example, if two
549-
schemas "#alice" and "#bob" both have an "allOf" property that refers to the other,
550-
a naive validator might get stuck in an infinite recursive loop trying to validate
551-
the instance.
552-
Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is
553-
undefined.
554-
</t>
555-
</section>
556-
557530
<section title="Base URI and Dereferencing">
558531
<section title="Initial Base URI">
559532
<t>
@@ -581,39 +554,61 @@
581554
This value SHOULD be normalized, and SHOULD NOT be an empty fragment &lt;#&gt;
582555
or an empty string &lt;&gt;.
583556
</t>
584-
<t>
585-
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
586-
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
587-
have one that is an empty string.
588-
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
589-
<cref>
590-
How should an "$id" URI reference containing a fragment with other components
591-
be interpreted? There are two cases: when the other components match
592-
the current base URI and when they change the base URI.
593-
</cref>
594-
</t>
595-
<t>
596-
To name subschemas in a JSON Schema document,
597-
subschemas can use "$id" to give themselves a document-local identifier.
598-
This is done by setting "$id" to a URI reference consisting
599-
only of a plain name fragment (not a JSON Pointer fragment).
600-
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
601-
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
602-
(":"), or periods (".").
603-
</t>
604-
<t>
605-
Providing a plain name fragment enables a subschema to be
606-
relocated within a schema without requiring that JSON
607-
Pointer references are updated.
608-
</t>
609-
<t>
610-
The effect of defining a fragment-only "$id" URI reference that neither
611-
matches the above requirements nor is a valid JSON pointer
612-
is not defined.
613-
</t>
614-
<t>
615-
For example:
557+
<section title="Identifying the root schema">
558+
<t>
559+
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
560+
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
561+
have one that is an empty string.
562+
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
563+
</t>
564+
</section>
565+
<section title="Changing the base URI within a schema file">
566+
<t>
567+
When an "$id" sets the base URI, the object containing that "$id" and all of
568+
its subschemas can be identified by using a JSON Pointer fragment starting
569+
from that location. This is true even of subschemas that further change the
570+
base URI. Therefore, a single subschema may be accessible by multiple URIs,
571+
each consisting of base URI declared in the subschema or a parent, along with
572+
a JSON Pointer fragment identifying the path from the schema object that
573+
declares the base to the subschema being identified. Examples of this are
574+
shown in section <xref target="idExamples" format="counter"></xref>.
575+
</t>
576+
</section>
577+
<section title="Location-independent identifiers">
578+
<t>
579+
Using JSON Pointer fragments requires knowledge of the structure of the schema.
580+
When writing schema documents with the intention to provide re-usable
581+
schemas, it may be preferable to use a plain name fragment that is not tied to
582+
any particular structural location. This allows a subschema to be relocated
583+
without requiring JSON Pointer references to be updated.
584+
</t>
585+
<t>
586+
To name subschemas in a JSON Schema document,
587+
subschemas can use "$id" to give themselves a document-local identifier.
588+
This is done by setting "$id" to a URI reference consisting
589+
only of a plain name fragment (not a JSON Pointer fragment).
590+
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
591+
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
592+
(":"), or periods (".").
593+
</t>
594+
<t>
595+
The effect of defining a fragment-only "$id" URI reference that neither
596+
matches the above requirements nor is a valid JSON pointer
597+
is not defined.
598+
<cref>
599+
How should an "$id" URI reference containing a fragment with other components
600+
be interpreted? There are two cases: when the other components match
601+
the current base URI and when they change the base URI.
602+
</cref>
603+
</t>
604+
</section>
605+
<section title="Schema identification examples" anchor="idExamples">
616606
<figure>
607+
<preamble>
608+
Consider the following schema, which shows "$id" being used to identify
609+
the root schema, change the base URI for subschemas, and assign plain
610+
name fragments to subschemas:
611+
</preamble>
617612
<artwork>
618613
<![CDATA[
619614
{
@@ -635,33 +630,120 @@
635630
]]>
636631
</artwork>
637632
</figure>
633+
<t>
634+
The schemas at the following URI-encoded <xref target="RFC6901">JSON
635+
Pointers</xref> (relative to the root schema) have the following
636+
base URIs, and are identifiable by any listed URI in accordance with
637+
Section <xref target="fragments" format="counter"></xref> above:
638+
</t>
639+
<t>
640+
<list style="hanging">
641+
<t hangText="# (document root)">
642+
<list>
643+
<t>http://example.com/root.json</t>
644+
<t>http://example.com/root.json#</t>
645+
</list>
646+
</t>
647+
<t hangText="#/definitions/A">
648+
<list>
649+
<t>http://example.com/root.json#foo</t>
650+
<t>http://example.com/root.json#/definitions/A</t>
651+
</list>
652+
</t>
653+
<t hangText="#/definitions/B">
654+
<list>
655+
<t>http://example.com/other.json</t>
656+
<t>http://example.com/other.json#</t>
657+
<t>http://example.com/root.json#/definitions/B</t>
658+
</list>
659+
</t>
660+
<t hangText="#/definitions/B/definitions/X">
661+
<list>
662+
<t>http://example.com/other.json#bar</t>
663+
<t>http://example.com/other.json#/definitions/X</t>
664+
<t>http://example.com/root.json#/definitions/B/definitions/X</t>
665+
</list>
666+
</t>
667+
<t hangText="#/definitions/B/definitions/Y">
668+
<list>
669+
<t>http://example.com/t/inner.json</t>
670+
<t>http://example.com/t/inner.json#</t>
671+
<t>http://example.com/other.json#/definitions/Y</t>
672+
<t>http://example.com/root.json#/definitions/B/definitions/Y</t>
673+
</list>
674+
</t>
675+
<t hangText="#/definitions/C">
676+
<list>
677+
<t>urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f</t>
678+
<t>urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f#</t>
679+
<t>http://example.com/root.json#/definitions/C</t>
680+
</list>
681+
</t>
682+
</list>
683+
</t>
684+
</section>
685+
</section>
686+
687+
<section title='Schema References With "$ref"'>
688+
<t>
689+
The "$ref" keyword is used to reference a schema, and provides the ability to
690+
validate recursive structures through self-reference.
638691
</t>
639692
<t>
640-
The schemas at the following URI-encoded <xref target="RFC6901">JSON
641-
Pointers</xref> (relative to the root schema) have the following
642-
base URIs, and are identifiable by either URI in accordance with
643-
Section <xref target="fragments" format="counter"></xref> above:
693+
An object schema with a "$ref" property MUST be interpreted as a "$ref" reference.
694+
The value of the "$ref" property MUST be a URI Reference.
695+
Resolved against the current URI base, it identifies the URI of a schema to use.
696+
All other properties in a "$ref" object MUST be ignored.
644697
</t>
645698
<t>
646-
<list style="hanging">
647-
<t hangText="# (document root)">http://example.com/root.json#</t>
648-
<t hangText="#/definitions/A">http://example.com/root.json#foo</t>
649-
<t hangText="#/definitions/B">http://example.com/other.json</t>
650-
<t hangText="#/definitions/B/definitions/X">http://example.com/other.json#bar</t>
651-
<t hangText="#/definitions/B/definitions/Y">http://example.com/t/inner.json</t>
652-
<t hangText="#/definitions/C">urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f</t>
653-
</list>
699+
The URI is not a network locator, only an identifier. A schema need not be
700+
downloadable from the address if it is a network-addressable URL, and
701+
implementations SHOULD NOT assume they should perform a network operation when they
702+
encounter a network-addressable URI.
703+
</t>
704+
<t>
705+
A schema MUST NOT be run into an infinite loop against a schema. For example, if two
706+
schemas "#alice" and "#bob" both have an "allOf" property that refers to the other,
707+
a naive validator might get stuck in an infinite recursive loop trying to validate
708+
the instance.
709+
Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is
710+
undefined.
654711
</t>
655-
<section title="Internal References">
712+
<section title="Loading a referenced schema">
713+
<t>
714+
To differentiate schemas between each other in a vast ecosystem, schemas are
715+
identified by URI. As specified above, this does not necessarily mean
716+
anything is downloaded, but instead JSON Schema implementations SHOULD
717+
already understand the schemas they will be using, including the URIs that
718+
identify them.
719+
</t>
720+
<t>
721+
Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
722+
schema and/or automatically associate a schema's "$id"-given URI, depending
723+
on the trust that the validator has in the schema. Such URIs and schemas
724+
can be supplied to an implementation prior to processing instances, or may
725+
be noted within a schema document as it is processed, producing associations
726+
as shown in section <xref target="idExamples" format="counter"></xref>.
727+
</t>
728+
<t>
729+
A schema MAY (and likely will) have multiple URIs, but there is no way for a
730+
URI to identify more than one schema. When multiple schemas try to identify
731+
with the same URI, validators SHOULD raise an error condition.
732+
</t>
733+
</section>
734+
<section title="Dereferencing">
656735
<t>
657736
Schemas can be identified by any URI that has been given to them, including
658-
a JSON Pointer or their URI given directly by "$id".
737+
a JSON Pointer or their URI given directly by "$id". In all cases,
738+
dereferencing a "$ref" reference involves first resolving its value as a
739+
URI reference against the current base URI per
740+
<xref target="RFC3986">RFC 3986</xref>.
659741
</t>
660742
<t>
661-
Tools SHOULD take note of the URIs that schemas, including subschemas,
662-
provide for themselves using "$id". This is known as "Internal referencing".
743+
If the resulting URI identifies a schema within the current document, or
744+
within another schema document that has been made available to the implementation,
745+
then that schema SHOULD be used automatically.
663746
</t>
664-
665747
<t>
666748
For example, consider this schema:
667749
</t>
@@ -678,7 +760,8 @@
678760
"definitions": {
679761
"single": {
680762
"$id": "#item",
681-
"type": "integer"
763+
"type": "object",
764+
"additionalProperties": { "$ref": "other.json" }
682765
}
683766
}
684767
}
@@ -693,28 +776,22 @@
693776
<t>
694777
When an implementation then looks inside the &lt;#/items&gt; schema, it
695778
encounters the &lt;#item&gt; reference, and resolves this to
696-
&lt;http://example.net/root.json#item&gt; which is understood as the schema
697-
defined elsewhere in the same document without needing to
698-
resolve the fragment against the base URI.
699-
</t>
700-
</section>
701-
<section title="External References">
702-
<t>
703-
To differentiate schemas between each other in a vast ecosystem, schemas are
704-
identified by URI. As specified above, this does not necessarily mean
705-
anything is downloaded, but instead JSON Schema implementations SHOULD
706-
already understand the schemas they will be using, including the URIs that
707-
identify them.
708-
</t>
709-
<t>
710-
Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
711-
schema and/or automatically associate a schema's "$id"-given URI, depending
712-
on the trust that the validator has in the schema.
779+
&lt;http://example.net/root.json#item&gt;, which it has seen defined in
780+
this same document and can therefore use automatically.
713781
</t>
714782
<t>
715-
A schema MAY (and likely will) have multiple URIs, but there is no way for a
716-
URI to identify more than one schema. When multiple schemas try to identify
717-
with the same URI, validators SHOULD raise an error condition.
783+
When an implementation encounters the reference to "other.json", it resolves
784+
this to &lt;http://example.net/other.json&gt;, which is not defined in this
785+
document. If a schema with that identifier has otherwise been supplied to
786+
the implementation, it can also be used automatically.
787+
<cref>
788+
What should implementations do when the referenced schema is not known?
789+
Are there circumstances in which automatic network dereferencing is
790+
allowed? A same origin policy? A user-configurable option? In the
791+
case of an evolving API described by Hyper-Schema, it is expected that
792+
new schemas will be added to the system dynamically, so placing an
793+
absolute requirement of pre-loading schema documents is not feasible.
794+
</cref>
718795
</t>
719796
</section>
720797
</section>

0 commit comments

Comments
 (0)