schema = {
"items": {
"anyOf": [
{"type": "string", "maxLength": 2},
{"type": "integer", "minimum": 5}
instance = [{}, 3, "foo"]
v = Draft202012Validator(schema)
errors = sorted(v.iter_errors(instance), key=lambda e: e.path)
The error messages in this situation are not very helpful on their own.
for error in errors:
print(error.message)
outputs:
{} is not valid under any of the given schemas
3 is not valid under any of the given schemas
'foo' is not valid under any of the given schemas
If we look at ValidationError.path on each of the errors, we can find
out which elements in the instance correspond to each of the errors. In
this example, ValidationError.path will have only one element, which
will be the index in our list.
for error in errors:
print(list(error.path))
Since our schema contained nested subschemas, it can be helpful to look at
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 keywords like 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
exactly in the schema each of these errors come from. In the case of sub-errors
from the ValidationError.context attribute, this path will be relative
to the ValidationError.schema_path of the parent error.
for error in errors:
for suberror in sorted(error.context, key=lambda e: e.schema_path):
print(list(suberror.schema_path), suberror.message, sep=", ")
[0, 'type'], {} is not of type 'string'
[1, 'type'], {} is not of type 'integer'
[0, 'type'], 3 is not of type 'string'
[1, 'minimum'], 3 is less than the minimum of 5
[0, 'maxLength'], 'foo' is too long
[1, 'type'], 'foo' is not of type 'integer'
The string representation of an error combines some of these attributes for
easier debugging.
print(errors[1])
3 is not valid under any of the given schemas
Failed validating 'anyOf' in schema['items']:
{'anyOf': [{'type': 'string', 'maxLength': 2},
{'type': 'integer', 'minimum': 5}]}
On instance[1]:
ErrorTrees
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.
class jsonschema.exceptions.ErrorTree(errors: Iterable[ValidationError] = ())[source]
ErrorTrees make it easier to check which validations failed.
errors
The mapping of validation keywords to the error objects (usually jsonschema.exceptions.ValidationErrors) at this level of the tree.
__getitem__(index)[source]
Retrieve the child tree one level down at the given index.
If the index is not in the instance that this tree corresponds
to and is not known by this tree, whatever error would be raised
by instance.__getitem__ will be propagated (usually this is
some subclass of LookupError.
__setitem__(index: str | int, value: ErrorTree)[source]
Add an error to the tree at the given index.
Deprecated since version v4.20.0: Setting items on an ErrorTree is deprecated without replacement.
To populate a tree, provide all of its sub-errors when you
construct the tree.
schema = {
"type" : "array",
"items" : {"type" : "number", "enum" : [1, 2, 3]},
"minItems" : 3,
instance = ["spam", 2]
For clarity’s sake, the given instance has three errors under this schema:
v = Draft202012Validator(schema)
for error in sorted(v.iter_errors(["spam", 2]), key=str):
print(error.message)
'spam' is not of type 'number'
'spam' is not one of [1, 2, 3]
['spam', 2] is too short
Let’s construct an jsonschema.exceptions.ErrorTree so that we
can query the errors a bit more easily than by just iterating over the
error objects.
from jsonschema.exceptions import ErrorTree
tree = ErrorTree(v.iter_errors(instance))
As you can see, jsonschema.exceptions.ErrorTree
takes an iterable of ValidationErrors when constructing a tree so you can directly pass it the return value of a validator’s jsonschema.protocols.Validator.iter_errors method.
ErrorTrees support a number of useful operations. The first one we
might want to perform is to check whether a given element in our instance
failed validation. We do so using the in operator:
>>> 0 in tree
>>> 1 in tree
False
The interpretation here is that the 0th index into the instance ("spam")
did have an error (in fact it had 2), while the 1th index (2) did not (i.e.
it was valid).
If we want to see which errors a child had, we index into the tree and look at
the ErrorTree.errors attribute.
>>> sorted(tree[0].errors)
['enum', 'type']
Here we see that the enum and type keywords failed for
index 0. In fact ErrorTree.errors is a dict, whose values are the
ValidationErrors, so we can get at those directly if we want them.
>>> 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 validation
keyword failed for a given index, we check for its presence in
ErrorTree.errors:
>>> "enum" in tree[0].errors
>>> "minimum" in tree[0].errors
False
Finally, if you were paying close enough attention, you’ll notice that
we haven’t seen our minItems error appear anywhere yet. This is
because minItems is an error that applies globally to the instance
itself. So it appears in the root node of the tree.
>>> "minItems" in tree.errors
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 validation keyword to the
corresponding validation error.
best_match and relevance
The best_match function is a simple but useful function for attempting
to guess the most relevant error in a given bunch.
>>> from jsonschema import Draft202012Validator
>>> from jsonschema.exceptions import best_match
>>> schema = {
... "type": "array",
... "minItems": 3,
... }
>>> print(best_match(Draft202012Validator(schema).iter_errors(11)).message)
11 is not of type 'array'
jsonschema.exceptions.best_match(errors, key=<function by_relevance.<locals>.relevance>)[source]
Try to find an error that appears to be the best match among given errors.
In general, errors that are higher up in the instance (i.e. for which
ValidationError.path is shorter) are considered better matches,
since they indicate “more” is wrong with the instance.
If the resulting match is either oneOf or 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.
Parameters:
errors (collections.abc.Iterable) – the errors to select from. Do not provide a mixture of
errors from different validation attempts (i.e. from
different instances or schemas), since it won’t produce
sensical output.
key (collections.abc.Callable) – the key to use when sorting errors. See relevance and
transitively by_relevance for more details (the default is
to sort with the defaults of that function). Changing the
default is only useful if you want to change the function
that rates errors but still want the error context descent
done by this function.
Returns:
the best matching error, or None if the iterable was empty
This function is a heuristic. Its return value may change for a given
set of inputs from version to version if better heuristics are added.
jsonschema.exceptions.relevance(validation_error)
A key function that sorts errors based on heuristic relevance.
If you want to sort a bunch of errors entirely, you can use
this function to do so. Using this function as a key to e.g.
sorted or max will cause more relevant errors to be
considered greater than less relevant ones.
Within the different validation keywords that can fail, this
function considers anyOf and 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] validation
keywords you can create a custom version of this function with
by_relevance and provide a different set of each.
>>> schema = {
... "properties": {
... "name": {"type": "string"},
... "phones": {
... "properties": {
... "home": {"type": "string"}
... },
... },
... },
... }
>>> instance = {"name": 123, "phones": {"home": [123]}}
>>> errors = Draft202012Validator(schema).iter_errors(instance)
... e.path[-1]
... for e in sorted(errors, key=exceptions.relevance)
... ]
['home', 'name']
jsonschema.exceptions.by_relevance(weak=frozenset({'anyOf', 'oneOf'}), strong=frozenset({}))[source]
Create a key function that can be used to sort errors by relevance.
Parameters:
weak (set) – 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, anyOf
and oneOf are considered weak keywords and will be
superseded by other same-level validation errors.
strong (set) – a collection of validation keywords to consider to be
“strong”
ValidationError.validator_value
ValidationError.schema
ValidationError.relative_schema_path
ValidationError.absolute_schema_path
ValidationError.schema_path
ValidationError.relative_path
ValidationError.absolute_path
ValidationError.json_path
ValidationError.path
ValidationError.instance
ValidationError.context
ValidationError.cause
ValidationError.parent
ErrorTrees
