Skip to content

Commit b48cf71

Browse files
committed
revisit 'directive' behaviors text; add requirement about extensions redefining keywords
1 parent 50e9aca commit b48cf71

File tree

1 file changed

+18
-9
lines changed

1 file changed

+18
-9
lines changed

specs/jsonschema-core.md

+18-9
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,18 @@ Additional schema keywords MAY be defined by any entity. Save for explicit
394394
agreement, schema authors SHALL NOT expect these additional keywords to be
395395
supported by implementations that do not explicitly document such support.
396396

397+
Extension keywords MUST NOT interfere with the operation of keywords defined by
398+
this document or the companion JSON Schema Validation specificiation, and SHOULD
399+
NOT interfere with the operation of keywords defined by other extension
400+
documents.[^11]
401+
402+
[^11]: JSON Schema currently does not have a namespacing mechanism, which would
403+
allow multiple extensions to define the same keyword differently while also
404+
giving the schema author the ability to declare which definition is intended.
405+
Such a feature is planned for future releases. See the
406+
[Vocabularies / Extensions project](https://github.com/orgs/json-schema-org/projects/28/views/2)
407+
in GitHub for more information.
408+
397409
Implementations MAY provide the ability to register or load handlers for
398410
keywords that they do not support directly. The exact mechanism for registering
399411
and implementing such handlers is implementation-dependent.
@@ -422,26 +434,23 @@ defines three such behaviors[^7]:
422434

423435
- Assertions validate that an instance satisfies constraints, producing a
424436
boolean result: `true` if the constraints are satisfied; `false` otherwise.
425-
- Annotations attach information to instance locations that applications may use in any way they see
426-
fit.
437+
- Annotations attach information to instance locations that applications may use
438+
in any way they see fit.
427439
- Applicators apply subschemas to parts of the instance and combine their
428440
results.
429441

430442
[^7]: This specification also defines several operational directive keywords,
431-
such as `$id` and `$schema`. As such, these keywords do not exhibit these
432-
behaviors. However, it is recommended that extensions avoid defining additional
433-
directive keywords as they could interfere with schema processing and produce
434-
unexpected or undesirable results.
443+
such as `$id` and `$schema`, which do not exhibit these behaviors. Instead,
444+
these keywords provide metadata that instruct implementations on how to
445+
interpret and process the schema.
435446

436447
Extension keywords SHOULD be defined using these behaviors, keeping in mind that
437448
annotations in particular are extremely flexible. Complex behavior is usually
438449
better delegated to applications on the basis of annotation data than
439450
implemented directly as schema keywords. However, extension keywords MAY define
440451
other behaviors for specialized purposes.
441452

442-
Keywords which are not defined to exhibit a particular behavior MUST NOT affect
443-
that aspect of evaluation. For example, a keyword which does not act as an
444-
assertion MUST NOT affect the validation result.
453+
Implementations SHOULD NOT add unspecified behaviors to keywords.
445454

446455
For the purposes of this document, an instance "validating against a keyword"
447456
means that the keyword produces an assertion result of `true` if the instance

0 commit comments

Comments
 (0)