Prefer 'keyword' over 'validator' in docs.

In newer JSON Schema specifications we've standardized more
on this language rather than calling things validators (and such
a thing already has plenty of overloaded meaning here).

This commit doesn't do any deprecation, so there's still some
awkwardness in that ValidationError.validator is the keyword which
failed validation, and Validator.VALIDATORS is a mapping of keywords to
callables.

We may choose to do so later, but for now will save some API churn in
case something else changes.

Author: Julian

docs/errors.rst

@@ -36,29 +36,29 @@ raised or returned, depending on which method or function is used.
 
     .. attribute:: validator
 
-        The name of the failed `validator
+        The name of the failed `keyword
         <https://json-schema.org/draft/2020-12/json-schema-validation.html#name-a-vocabulary-for-structural>`_.
 
     .. attribute:: validator_value
 
-        The value for the failed validator in the schema.
+        The associated value for the failed keyword in the schema.
 
     .. attribute:: schema
 
         The full schema that this error came from. This is potentially a
         subschema from within the schema that was passed in originally,
-        or even an entirely different schema if a :validator:`$ref` was
+        or even an entirely different schema if a :kw:`$ref` was
         followed.
 
     .. attribute:: relative_schema_path
 
-        A `collections.deque` containing the path to the failed
-        validator within the schema.
+        A `collections.deque` containing the path to the failed keyword
+        within the schema.
 
     .. attribute:: absolute_schema_path
 
         A `collections.deque` containing the path to the failed
-        validator within the schema, but always relative to the
+        keyword within the schema, but always relative to the
         *original* schema as opposed to any subschema (i.e. the one
         originally passed into a validator class, *not* `schema`\).
 
@@ -179,7 +179,7 @@ the specific part of the instance and subschema that caused each of the errors.
 This can be seen with the `ValidationError.instance` and
 `ValidationError.schema` attributes.
 
-With validators like :validator:`anyOf`, the `ValidationError.context`
+With keywords like :kw:`anyOf`, the `ValidationError.context`
 attribute can be used to see the sub-errors which caused the failure. Since
 these errors actually came from two separate subschemas, it can be helpful to
 look at the `ValidationError.schema_path` attribute as well to see where
@@ -224,8 +224,8 @@ easier debugging.
 ErrorTrees
 ----------
 
-If you want to programmatically be able to query which properties or validators
-failed when validating a given instance, you probably will want to do so using
+If you want to programmatically query which validation keywords
+failed when validating a given instance, you may want to do so using
 `jsonschema.exceptions.ErrorTree` objects.
 
 .. autoclass:: jsonschema.exceptions.ErrorTree
@@ -235,7 +235,7 @@ failed when validating a given instance, you probably will want to do so using
 
     .. attribute:: errors
 
-        The mapping of validator names to the error objects (usually
+        The mapping of validator keywords to the error objects (usually
         `jsonschema.exceptions.ValidationError`\s) at this level
         of the tree.
 
@@ -301,18 +301,17 @@ the `ErrorTree.errors` attribute.
     >>> sorted(tree[0].errors)
     ['enum', 'type']
 
-Here we see that the :validator:`enum` and :validator:`type` validators failed
-for index ``0``. In fact `ErrorTree.errors` is a dict, whose values are
-the `ValidationError`\s, so we can get at those directly if we want
-them.
+Here we see that the :kw:`enum` and :kw:`type` keywords failed for
+index ``0``. In fact `ErrorTree.errors` is a dict, whose values are the
+`ValidationError`\s, so we can get at those directly if we want them.
 
 .. doctest::
 
     >>> print(tree[0].errors["type"].message)
     'spam' is not of type 'number'
 
-Of course this means that if we want to know if a given named
-validator failed for a given index, we check for its presence in
+Of course this means that if we want to know if a given validation
+keyword failed for a given index, we check for its presence in
 `ErrorTree.errors`:
 
 .. doctest::
@@ -323,9 +322,9 @@ validator failed for a given index, we check for its presence in
     >>> "minimum" in tree[0].errors
     False
 
-Finally, if you were paying close enough attention, you'll notice that we
-haven't seen our :validator:`minItems` error appear anywhere yet. This is
-because :validator:`minItems` is an error that applies globally to the instance
+Finally, if you were paying close enough attention, you'll notice that
+we haven't seen our :kw:`minItems` error appear anywhere yet. This is
+because :kw:`minItems` is an error that applies globally to the instance
 itself. So it appears in the root node of the tree.
 
 .. doctest::
@@ -336,9 +335,9 @@ itself. So it appears in the root node of the tree.
 That's all you need to know to use error trees.
 
 To summarize, each tree contains child trees that can be accessed by
-indexing the tree to get the corresponding child tree for a given index
-into the instance. Each tree and child has a `ErrorTree.errors`
-attribute, a dict, that maps the failed validator name to the
+indexing the tree to get the corresponding child tree for a given
+index into the instance. Each tree and child has a `ErrorTree.errors`
+attribute, a dict, that maps the failed validation keyword to the
 corresponding validation error.
 
 
@@ -373,14 +372,14 @@ to guess the most relevant error in a given bunch.
     `sorted` or `max` will cause more relevant errors to be
     considered greater than less relevant ones.
 
-    Within the different validators that can fail, this function
-    considers :validator:`anyOf` and :validator:`oneOf` to be *weak*
-    validation errors, and will sort them lower than other validators at
-    the same level in the instance.
+    Within the different validation keywords that can fail, this
+    function considers :kw:`anyOf` and :kw:`oneOf` to be *weak*
+    validation errors, and will sort them lower than other errors at the
+    same level in the instance.
 
-    If you want to change the set of weak [or strong] validators you can create
-    a custom version of this function with `by_relevance` and provide a
-    different set of each.
+    If you want to change the set of weak [or strong] validation
+    keywords you can create a custom version of this function with
+    `by_relevance` and provide a different set of each.
 
 .. doctest::
 

docs/faq.rst

@@ -6,7 +6,7 @@ Frequently Asked Questions
 My schema specifies format validation. Why do invalid instances seem valid?
 ---------------------------------------------------------------------------
 
-The :validator:`format` validator can be a bit of a stumbling block for new
+The :kw:`format` keyword can be a bit of a stumbling block for new
 users working with JSON Schema.
 
 In a schema such as:
@@ -16,40 +16,40 @@ In a schema such as:
     {"type": "string", "format": "date"}
 
 JSON Schema specifications have historically differentiated between the
-:validator:`format` validator and other validators. In particular, the
-:validator:`format` validator was specified to be *informational* as much
+:kw:`format` keyword and other keywords. In particular, the
+:kw:`format` keyword was specified to be *informational* as much
 as it may be used for validation.
 
 In other words, for many use cases, schema authors may wish to use
-values for the :validator:`format` validator but have no expectation
+values for the :kw:`format` keyword but have no expectation
 they be validated alongside other required assertions in a schema.
 
 Of course this does not represent all or even most use cases -- many
 schema authors *do* wish to assert that instances conform fully, even to
 the specific format mentioned.
 
 In drafts prior to ``draft2019-09``, the decision on whether to
-automatically enable :validator:`format` validation was left up to
+automatically enable :kw:`format` validation was left up to
 validation implementations such as this one.
 
 This library made the choice to leave it off by default, for two reasons:
 
     * for forward compatibility and implementation complexity reasons
-      -- if :validator:`format` validation were on by default, and a
+      -- if :kw:`format` validation were on by default, and a
       future draft of JSON Schema introduced a hard-to-implement format,
       either the implementation of that format would block releases of
       this library until it were implemented, or the behavior surrounding
-      :validator:`format` would need to be even more complex than simply
+      :kw:`format` would need to be even more complex than simply
       defaulting to be on. It therefore was safer to start with it off,
       and defend against the expectation that a given format would always
       automatically work.
 
     * given that a common use of JSON Schema is for portability across
       languages (and therefore implementations of JSON Schema), so that
-      users be aware of this point itself regarding :validator:`format`
+      users be aware of this point itself regarding :kw:`format`
       validation, and therefore remember to check any *other*
       implementations they were using to ensure they too were explicitly
-      enabled for :validator:`format` validation.
+      enabled for :kw:`format` validation.
 
 As of ``draft2019-09`` however, the opt-out by default behavior
 mentioned here is now *required* for all validators.
@@ -132,11 +132,11 @@ Why doesn't my schema's default property set the default on my instance?
 ------------------------------------------------------------------------
 
 The basic answer is that the specification does not require that
-:validator:`default` actually do anything.
+:kw:`default` actually do anything.
 
 For an inkling as to *why* it doesn't actually do anything, consider
-that none of the other validators modify the instance either. More
-importantly, having :validator:`default` modify the instance can produce
+that none of the other keywords modify the instance either. More
+importantly, having :kw:`default` modify the instance can produce
 quite peculiar things. It's perfectly valid (and perhaps even useful)
 to have a default that is not valid under the schema it lives in! So an
 instance modified by the default would pass validation the first time,
@@ -179,15 +179,15 @@ be valid under the schema.)
         # Example usage:
         obj = {}
         schema = {'properties': {'foo': {'default': 'bar'}}}
-        # Note jsonschem.validate(obj, schema, cls=DefaultValidatingValidator)
-        # will not work because the metaschema contains `default` directives.
+        # Note jsonschema.validate(obj, schema, cls=DefaultValidatingValidator)
+        # will not work because the metaschema contains `default` keywords.
         DefaultValidatingValidator(schema).validate(obj)
         assert obj == {'foo': 'bar'}
 
 
-See the above-linked document for more info on how this works, but
-basically, it just extends the :validator:`properties` validator on
-a `jsonschema.Draft202012Validator` to then go ahead and update all the
+See the above-linked document for more info on how this works,
+but basically, it just extends the :kw:`properties` keyword on a
+`jsonschema.Draft202012Validator` to then go ahead and update all the
 defaults.
 
 .. note::

docs/jsonschema_role.py

@@ -34,7 +34,7 @@ def setup(app):
 
     path = os.path.join(app.config.cache_path, "spec.html")
     spec = fetch_or_load(path)
-    app.add_role("validator", docutils_does_not_allow_using_classes(spec))
+    app.add_role("kw", docutils_does_not_allow_using_classes(spec))
 
     return dict(version=__version__, parallel_read_safe=True)
 
@@ -84,9 +84,9 @@ def docutils_does_not_allow_using_classes(spec):
     keeping a dict.
     """
 
-    def validator(name, raw_text, text, lineno, inliner):
+    def keyword(name, raw_text, text, lineno, inliner):
         """
-        Link to the JSON Schema documentation for a validator.
+        Link to the JSON Schema documentation for a keyword.
 
         Arguments:
 
@@ -143,4 +143,4 @@ def validator(name, raw_text, text, lineno, inliner):
         reference = nodes.reference(raw_text, text, refuri=uri)
         return [reference], []
 
-    return validator
+    return keyword

docs/validate.rst

@@ -24,8 +24,8 @@ The simplest way to validate an instance under a given schema is to use the
 The Validator Protocol
 -----------------------
 
-`jsonschema` defines a protocol that all validator
-classes should adhere to.
+`jsonschema` defines a protocol that all validator classes should adhere
+to.
 
 .. autoclass:: jsonschema.protocols.Validator
     :members:
@@ -38,7 +38,7 @@ more information see `creating-validators`.
 Type Checking
 -------------
 
-To handle JSON Schema's :validator:`type` property, a `Validator` uses
+To handle JSON Schema's :kw:`type` keyword, a `Validator` uses
 an associated `TypeChecker`. The type checker provides an immutable
 mapping between names of types and functions that can test if an instance is
 of that type. The defaults are suitable for most users - each of the
@@ -65,7 +65,7 @@ Validating With Additional Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Occasionally it can be useful to provide additional or alternate types when
-validating the JSON Schema's :validator:`type` property.
+validating JSON Schema's :kw:`type` keyword.
 
 `jsonschema` tries to strike a balance between performance in the common
 case and generality. For instance, JSON Schema defines a ``number`` type, which
@@ -158,7 +158,7 @@ Draft 2020-12 meta-schema, you could use:
 Validating Formats
 ------------------
 
-JSON Schema defines the :validator:`format` property which can be used to check
+JSON Schema defines the :kw:`format` keyword which can be used to check
 if primitive types (``string``\s, ``number``\s, ``boolean``\s) conform to
 well-defined formats. By default, no validation is enforced, but optionally,
 validation can be enabled by hooking in a format-checking object into an
@@ -282,7 +282,7 @@ Checker                    Notes
     and that that recipient is the correct one the email is intended
     for, and since many valid email addresses are in many places
     incorrectly rejected, and many invalid email addresses are in many
-    places incorrectly accepted, the ``email`` format validator only
+    places incorrectly accepted, the ``email`` format keyword only
     provides a sanity check, not full rfc5322_ validation.
 
     The same applies to the ``idn-email`` format.

jsonschema/_legacy_validators.py

@@ -6,7 +6,7 @@ def ignore_ref_siblings(schema):
     """
     Ignore siblings of ``$ref`` if it is present.
 
-    Otherwise, return all validators.
+    Otherwise, return all keywords.
 
     Suitable for use with `create`'s ``applicable_validators`` argument.
     """
@@ -47,9 +47,9 @@ def dependencies_draft4_draft6_draft7(
     schema,
 ):
     """
-    Support for the ``dependencies`` validator from pre-draft 2019-09.
+    Support for the ``dependencies`` keyword from pre-draft 2019-09.
 
-    In later drafts, the validator was split into separate
+    In later drafts, the keyword was split into separate
     ``dependentRequired`` and ``dependentSchemas`` validators.
     """
     if not validator.is_type(instance, "object"):

jsonschema/_utils.py

@@ -224,7 +224,8 @@ def find_evaluated_item_indexes_by_schema(validator, instance, schema):
 
         try:
             evaluated_indexes += find_evaluated_item_indexes_by_schema(
-                validator, instance, resolved)
+                validator, instance, resolved,
+            )
         finally:
             validator.resolver.pop_scope()
 

jsonschema/exceptions.py

@@ -315,15 +315,16 @@ def by_relevance(weak=WEAK_MATCHES, strong=STRONG_MATCHES):
 
     Arguments:
         weak (set):
-            a collection of validator names to consider to be "weak".
-            If there are two errors at the same level of the instance
-            and one is in the set of weak validator names, the other
-            error will take priority. By default, :validator:`anyOf` and
-            :validator:`oneOf` are considered weak validators and will
-            be superseded by other same-level validation errors.
+            a collection of validation keywords to consider to be
+            "weak".  If there are two errors at the same level of the
+            instance and one is in the set of weak validation keywords,
+            the other error will take priority. By default, :kw:`anyOf`
+            and :kw:`oneOf` are considered weak keywords and will be
+            superseded by other same-level validation errors.
 
         strong (set):
-            a collection of validator names to consider to be "strong"
+            a collection of validation keywords to consider to be
+            "strong"
     """
     def relevance(error):
         validator = error.validator
@@ -347,10 +348,10 @@ def best_match(errors, key=relevance):
     `ValidationError.path` is shorter) are considered better matches,
     since they indicate "more" is wrong with the instance.
 
-    If the resulting match is either :validator:`oneOf` or :validator:`anyOf`,
-    the *opposite* assumption is made -- i.e. the deepest error is picked,
-    since these validators only need to match once, and any other errors may
-    not be relevant.
+    If the resulting match is either :kw:`oneOf` or :kw:`anyOf`, the
+    *opposite* assumption is made -- i.e. the deepest error is picked,
+    since these keywords only need to match once, and any other errors
+    may not be relevant.
 
     Arguments:
         errors (collections.abc.Iterable):