diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 851635fc..60a976f0 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -198,14 +198,19 @@
schema document begins by applying
the root schema to the complete instance
document. From there, keywords known as applicators are used to determine
- which additional subschemas are applied. Subschemas may be applied in-place
- to the current location, or to a child location. The subschemas may be all
- or part of the keyword's value, or the keyword's value may identify one
- or more schemas in a way defined by the keyword.
+ which additional schemas are applied. Such schemas may be applied in-place
+ to the current location, or to a child location.
- Applicator keywords also define how subschema boolean
- assertion
+ The schemas to be applied may be present as subschemas comprising all or
+ part of the keyword's value. Alternatively, an applicator may refer to
+ a schema elsewhere in the same schema document, or in a different one.
+ The mechanism for identifying such referred schemas is defined by the
+ keyword.
+
+
+ Applicator keywords also define how subschema or referred schema
+ boolean assertion
results are modified and/or combined to produce the boolean result
of the applicator. Applicators may apply any boolean logic operation
to the assertion results of subschemas, but MUST NOT introduce new
@@ -565,6 +570,34 @@
As with the root schema, a subschema is either an object or a boolean.
+
+
+ As noted in , an applicator keyword may
+ refer to a schema to be applied, rather than including it as a
+ subschema in the applicator's value. In such situations, the
+ schema being applied is known as the referred schema, while
+ the schema containing the applicator keyword is the referring schema.
+
+
+ While root schemas and subschemas are static concepts based on a
+ schema's position within a schema document, referred and referring
+ schemas are dynamic. Different pairs of schemas may find themselves
+ in various referred and referring arrangements during the evaluation
+ of an instance against a schema.
+
+
+ For some by-reference applicators, such as
+ "$ref", the referred schema can be determined
+ by static analysis of the schema document. Others may take evaluation
+ context into account, and only be resolvable in the process of evaluating
+ with an instance.
+
+ Assuming some form of dynamic reference keyword is introduced
+ related to GitHub issue #558, this section will be updated
+ to make a concrete reference to that keyword for clarification.
+
+
+
@@ -920,7 +953,7 @@
-
+
The "$ref" keyword is used to reference a schema, and provides the ability to
validate recursive structures through self-reference.