Skip to content

Commit c2b342d

Browse files
committed
initial scopes updates
1 parent 5c57ee7 commit c2b342d

File tree

1 file changed

+24
-11
lines changed

1 file changed

+24
-11
lines changed

specs/jsonschema-core.md

+24-11
Original file line numberDiff line numberDiff line change
@@ -451,21 +451,31 @@ further change the assertion result.
451451

452452
While most JSON Schema keywords can be evaluated on their own, or at most need
453453
to take into account the values or results of adjacent keywords in the same
454-
schema object, a few have more complex behavior.
454+
schema object, a few have more complex behavior. This behavior is generally
455+
governed by the scope of the keyword.
456+
457+
This specification defines two such scopes: lexical and dynamic.
458+
459+
#### Lexical Scope
455460

456461
The lexical scope of a keyword is determined by the nested JSON data structure
457462
of objects and arrays. The largest such scope is an entire schema document. The
458463
smallest scope is a single schema object with no subschemas.
459464

460-
Keywords MAY be defined with a partial value, such as a IRI reference, which
461-
must be resolved against another value, such as another IRI reference or a full
462-
IRI, which is found through the lexical structure of the JSON document. The
463-
`$id`, `$ref`, and `$dynamicRef` core keywords, and the "base" JSON Hyper-Schema
464-
keyword, are examples of this sort of behavior.
465+
Keywords MAY be defined with a partial value which must be resolved against
466+
another value found within the lexical structure of the JSON document. The
467+
`$id`, `$schema`, and `$ref` core keywords, and the `base` JSON Hyper-Schema
468+
keyword, are some such keywords. For example, an `$id` keyword found in an
469+
embedded schema resource may have a value that is a relative IRI. This value
470+
must be resolved against another `$id` keyword found in an ancestor subschema,
471+
or the root schema, to produce an absolute IRI which fully identifies that
472+
embedded schema resource.
465473

466474
Note that some keywords, such as `$schema`, apply to the lexical scope of the
467475
entire schema resource, and therefore MUST only appear in a schema resource's
468-
root schema.
476+
root object.
477+
478+
#### Dynamic Scope
469479

470480
Other keywords may take into account the dynamic scope that exists during the
471481
evaluation of a schema, typically together with an instance document. The
@@ -895,8 +905,10 @@ If this IRI identifies a retrievable resource, that resource SHOULD be of media
895905
type `application/schema+json`.
896906

897907
The `$schema` keyword SHOULD be used in the document root schema object, and MAY
898-
be used in the root schema objects of embedded schema resources. When the
899-
keyword appears in a non-resource root schema object, the behavior is undefined.
908+
be used in the root schema objects of embedded schema resources. This keyword
909+
MUST NOT appear in a subschema that is not also the root object of a schema
910+
resource (see {{id-keyword}} for more information regarding defining embedded
911+
schema resources.)
900912

901913
Values for this property are defined elsewhere in this and other documents, and
902914
by other parties.
@@ -918,8 +930,9 @@ to establish a base IRI in order to resolve the reference.
918930
#### The `$id` Keyword {#id-keyword}
919931

920932
An `$id` keyword in a schema or subschema identifies that schema or subschema as
921-
a distinct schema resource. The value for this keyword MUST be a string, and
922-
MUST represent a valid IRI reference without a fragment.
933+
a distinct schema resource and defines a new lexical scope. The value for this
934+
keyword MUST be a string, and MUST represent a valid IRI reference without a
935+
fragment.
923936

924937
When the value of this keyword is resolved against the current base IRI, the
925938
resulting absolute IRI then serves as the identifier for the schema resource and

0 commit comments

Comments
 (0)