Skip to content

Commit d9a5075

Browse files
handrewshandrews
committed
Consolidate sections on reference keywords.
This commit *only* includes formatting changes: * New overall section title * New section title for the now sub-section on "$ref" * "$ref" subsection indented and wrapped to 100 characters * "$recurse" section moved to right after "$ref" sub-section * "$recurse subsection indented and wrapped to 100 characters * Other reference subsections wrapped to 100 characters as needed The next commit will update the actual text.
1 parent 44ab14e commit d9a5075

File tree

1 file changed

+117
-114
lines changed

1 file changed

+117
-114
lines changed

‎jsonschema-core.xml

Lines changed: 117 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -791,40 +791,125 @@
791791
</section>
792792

793793
<section title='Schema References With "$ref"'>
794-
<t>
795-
The "$ref" keyword is used to reference a schema, and provides the ability to
796-
validate recursive structures through self-reference.
797-
</t>
798-
<t>
799-
An object schema with a "$ref" property MUST be interpreted as a "$ref" reference.
800-
The value of the "$ref" property MUST be a URI Reference.
801-
Resolved against the current URI base, it identifies the URI of a schema to use.
802-
All other properties in a "$ref" object MUST be ignored.
803-
</t>
804-
<t>
805-
The URI is not a network locator, only an identifier. A schema need not be
806-
downloadable from the address if it is a network-addressable URL, and
807-
implementations SHOULD NOT assume they should perform a network operation when they
808-
encounter a network-addressable URI.
809-
</t>
810-
<t>
811-
A schema MUST NOT be run into an infinite loop against a schema. For example, if two
812-
schemas "#alice" and "#bob" both have an "allOf" property that refers to the other,
813-
a naive validator might get stuck in an infinite recursive loop trying to validate
814-
the instance.
815-
Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is
816-
undefined.
817-
</t>
794+
<section title='Direct References with "$ref"'>
795+
<t>
796+
The "$ref" keyword is used to reference a schema, and provides the ability
797+
to validate recursive structures through self-reference.
798+
</t>
799+
<t>
800+
An object schema with a "$ref" property MUST be interpreted as a "$ref"
801+
reference. The value of the "$ref" property MUST be a URI Reference.
802+
Resolved against the current URI base, it identifies the URI of a schema
803+
to use. All other properties in a "$ref" object MUST be ignored.
804+
</t>
805+
<t>
806+
The URI is not a network locator, only an identifier. A schema need not be
807+
downloadable from the address if it is a network-addressable URL, and
808+
implementations SHOULD NOT assume they should perform a network operation
809+
when they encounter a network-addressable URI.
810+
</t>
811+
<t>
812+
A schema MUST NOT be run into an infinite loop against a schema. For
813+
example, if two schemas "#alice" and "#bob" both have an "allOf" property
814+
that refers to the other, a naive validator might get stuck in an infinite
815+
recursive loop trying to validate the instance. Schemas SHOULD NOT make
816+
use of infinite recursive nesting like this; the behavior is undefined.
817+
</t>
818+
</section>
819+
820+
<section title='Recursive references with "$recurse"'>
821+
<t>
822+
This keyword's value MUST be the boolean literal true.
823+
<cref>
824+
Future drafts may extend the usage with other values. The immediate
825+
use case does not require any targets other than the entry point
826+
root, and a regular fragment URI reference does not provide the
827+
correct semantics. Should other values be added in the future,
828+
it is expected that a boolean true value will remain an alias for
829+
this original use case.
830+
</cref>
831+
</t>
832+
<t>
833+
The presence of this keyword with a boolean true value indicates that,
834+
during processing, it MUST be treated as a reference to the
835+
<xref target="schema-documents">schema document</xref> where processing
836+
was initiated.
837+
</t>
838+
<t>
839+
This document, known as the entry point schema, is the schema document that
840+
was initially supplied to the implementation, as opposed to schema documents
841+
that were processed as a result of following a "$ref" reference. Note that
842+
even if processing began at a subschema within a document, the "$recurse"
843+
target MUST be the root of the document.
844+
</t>
845+
<t>
846+
Aside from the dynamic definition of the reference target, a "$recurse"
847+
reference MUST behave identically to a "$ref" reference.
848+
</t>
849+
<figure>
850+
<preamble>
851+
Given the following schemas:
852+
</preamble>
853+
<artwork>
854+
<![CDATA[
855+
{
856+
"$schema": "http://json-schema.org/draft-08/schema#",
857+
"$id": "https://example.com/base",
858+
"properties": {
859+
"local": {
860+
"$ref": "#",
861+
},
862+
"recursive": {
863+
"$recurse": true
864+
}
865+
}
866+
}
867+
868+
{
869+
"$schema": "http://json-schema.org/draft-08/schema#",
870+
"$id": "https://example.com/extension",
871+
"properties": {
872+
"extended": {
873+
"$ref": "https://example.com/base",
874+
}
875+
}
876+
}
877+
]]>
878+
</artwork>
879+
</figure>
880+
<t>
881+
When an implementation begins processing with the
882+
"https://example.com/base" schema, both the "local" and "recursive"
883+
references resolve to "https://example.com/base". The entry point
884+
schema and the schema being processed are the same.
885+
</t>
886+
<t>
887+
However, when an implementation begins processing with the
888+
"https://example.com/extension" schema, and processes the
889+
"https://example.com/base" schema as a result of following the "$ref"
890+
within the "extended" property, now the entry point schema is
891+
"https://example.com/extension".
892+
</t>
893+
<t>
894+
Therefore the "local" property's reference
895+
still resolves to "https://example.com/base" while the "recursive"
896+
property's reference now resolves to "https://example.com/extension".
897+
This behavior remains the same even if the implementation begins processing
898+
at "https://example.com/extension#/properties/extended".
899+
</t>
900+
</section>
901+
818902
<section title="Loading a referenced schema">
819903
<t>
820-
The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
821-
but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
822-
and the URIs that identify them.
904+
The use of URIs to identify remote schemas does not necessarily mean
905+
anything is downloaded, but instead JSON Schema implementations SHOULD
906+
understand ahead of time which schemas they will be using, and the URIs
907+
that identify them.
823908
</t>
824909
<t>
825-
When schemas are downloaded,
826-
for example by a generic user-agent that doesn't know until runtime which schemas to download,
827-
see <xref target="hypermedia">Usage for Hypermedia</xref>.
910+
When schemas are downloaded, for example by a generic user-agent that
911+
doesn't know until runtime which schemas to download, see
912+
<xref target="hypermedia">Usage for Hypermedia</xref>.
828913
</t>
829914
<t>
830915
Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
@@ -850,8 +935,8 @@
850935
</t>
851936
<t>
852937
If the resulting URI identifies a schema within the current document, or
853-
within another schema document that has been made available to the implementation,
854-
then that schema SHOULD be used automatically.
938+
within another schema document that has been made available to the
939+
implementation, then that schema SHOULD be used automatically.
855940
</t>
856941
<t>
857942
For example, consider this schema:
@@ -905,88 +990,6 @@
905990
</section>
906991
</section>
907992

908-
<section title='Recursive references with "$recurse"'>
909-
<t>
910-
This keyword's value MUST be the boolean literal true.
911-
<cref>
912-
Future drafts may extend the usage with other values. The immediate
913-
use case does not require any targets other than the entry point
914-
root, and a regular fragment URI reference does not provide the
915-
correct semantics. Should other values be added in the future,
916-
it is expected that a boolean true value will remain an alias for
917-
this original use case.
918-
</cref>
919-
</t>
920-
<t>
921-
The presence of this keyword with a boolean true value indicates that,
922-
during processing, it MUST be treated as a reference to the
923-
<xref target="schema-documents">schema document</xref> where processing
924-
was initiated.
925-
</t>
926-
<t>
927-
This document, known as the entry point schema, is the schema document that
928-
was initially supplied to the implementation, as opposed to schema documents
929-
that were processed as a result of following a "$ref" reference. Note that
930-
even if processing began at a subschema within a document, the "$recurse"
931-
target MUST be the root of the document.
932-
</t>
933-
<t>
934-
Aside from the dynamic definition of the reference target, a "$recurse"
935-
reference MUST behave identically to a "$ref" reference.
936-
</t>
937-
<figure>
938-
<preamble>
939-
Given the following schemas:
940-
</preamble>
941-
<artwork>
942-
<![CDATA[
943-
{
944-
"$schema": "http://json-schema.org/draft-08/schema#",
945-
"$id": "https://example.com/base",
946-
"properties": {
947-
"local": {
948-
"$ref": "#",
949-
},
950-
"recursive": {
951-
"$recurse": true
952-
}
953-
}
954-
}
955-
956-
{
957-
"$schema": "http://json-schema.org/draft-08/schema#",
958-
"$id": "https://example.com/extension",
959-
"properties": {
960-
"extended": {
961-
"$ref": "https://example.com/base",
962-
}
963-
}
964-
}
965-
]]>
966-
</artwork>
967-
</figure>
968-
<t>
969-
When an implementation begins processing with the
970-
"https://example.com/base" schema, both the "local" and "recursive"
971-
references resolve to "https://example.com/base". The entry point
972-
schema and the schema being processed are the same.
973-
</t>
974-
<t>
975-
However, when an implementation begins processing with the
976-
"https://example.com/extension" schema, and processes the
977-
"https://example.com/base" schema as a result of following the "$ref"
978-
within the "extended" property, now the entry point schema is
979-
"https://example.com/extension".
980-
</t>
981-
<t>
982-
Therefore the "local" property's reference
983-
still resolves to "https://example.com/base" while the "recursive" property's
984-
reference now resolves to "https://example.com/extension".
985-
This behavior remains the same even if the implementation begins processing
986-
at "https://example.com/extension#/properties/extended".
987-
</t>
988-
</section>
989-
990993
<section title='Schema Re-Use With "$defs"'>
991994
<t>
992995
The "$defs" keyword provides a standardized location for schema

0 commit comments

Comments
 (0)