A collections.deque containing the path to the failed
validator 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, notschema).

A collections.deque containing the path to the
offending element within the instance. The absolute path
is always relative to the original instance that was
validated (i.e. the one passed into a validation method, notinstance). The deque can be empty if the error happened
at the root of the instance.

The instance that was being validated. This will differ from
the instance originally passed into validate() if the
validator object was in the process of validating a (possibly
nested) element within the top-level instance. The path within
the top-level instance (i.e. ValidationError.path) could
be used to find this object, but it is provided for convenience.

If the error was caused by errors in subschemas, the list of errors
from the subschemas will be available on this property. The
schema_path and path of these errors will be relative
to the parent error.

The error messages in this situation are not very helpful on their own.

forerrorinerrors: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 path on each of the errors, we can find
out which elements in the instance correspond to each of the errors. In
this example, path will have only one element, which
will be the index in our list.

forerrorinerrors:print(list(error.path))

[0]
[1]
[2]

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 instance and
schema attributes.

With validators like anyOf, the 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 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 context attribute, this path will be relative
to the schema_path of the parent error.

[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': [{'maxLength': 2, 'type': 'string'},
{'minimum': 5, 'type': 'integer'}]}
On instance[1]:
3

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.

'spam' is not of type 'number'
'spam' is not one of [1, 2, 3]
['spam', 2] is too short

Let’s construct an ErrorTree so that we can query the errors a bit
more easily than by just iterating over the error objects.

tree=ErrorTree(v.iter_errors(instance))

As you can see, ErrorTree takes an iterable of
ValidationErrors when constructing a tree so you
can directly pass it the return value of a validator object’s
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:

>>> 0intreeTrue>>> 1intreeFalse

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 errors attribute.

>>> sorted(tree[0].errors)['enum', 'type']

Here we see that the enum and type validators failed
for index 0. In fact 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 named
validator failed for a given index, we check for its presence in
errors:

>>> "enum"intree[0].errorsTrue>>> "minimum"intree[0].errorsFalse

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"intree.errorsTrue

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 errors
attribute, a dict, that maps the failed validator name to the
corresponding validation error.

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 validators only need to match once, and any other errors may
not be relevant.

Parameters:

errors (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 (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 decension done by
this function.

Returns:

the best matching error, or None if the iterable was empty

Note

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.

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 validators that can fail, this function
considers anyOf and oneOf to be weak
validation errors, and will sort them lower than other validators 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.

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, anyOf
and oneOf are considered weak validators and will
be superceded by other same-level validation errors.

strong (set) – a collection of validator names to consider to
be “strong”