Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 0b1a062

Browse files
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

Lines changed: 174 additions & 97 deletions
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 <xreftarget="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 <xreftarget="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)

AltStyle によって変換されたページ (->オリジナル) /