1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
==========================
Handling Validation Errors
==========================
.. currentmodule:: jsonschema
When an invalid instance is encountered, a :exc:`ValidationError` will be
raised or returned, depending on which method or function is used.
.. autoexception:: ValidationError
The instance didn't properly validate under the provided schema.
.. attribute:: message
A human readable message explaining the error.
.. attribute:: validator_keyword
The failed validator.
.. attribute:: validator_value
The value for the failed validator in the schema.
.. attribute:: schema
The full (sub)schema that this error came from.
.. attribute:: schema_path
A deque containing the path to the failed validator within the schema.
.. attribute:: path
A deque containing the path to the offending element (or an empty deque
if the error happened globally).
.. attribute:: instance
The instance that was being validated.
.. attribute:: context
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.
In case an invalid schema itself is encountered, a :exc:`SchemaError` is
raised.
.. autoexception:: SchemaError
The provided schema is malformed.
The same attributes are present as for :exc:`ValidationError`\s.
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
:class:`ErrorTree` objects.
.. autoclass:: ErrorTree
:members:
Consider the following example:
.. code-block:: python
>>> from jsonschema import ErrorTree, Draft3Validator
>>> 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:
.. code-block:: python
>>> v = Draft3Validator(schema)
>>> for error in sorted(v.iter_errors(["spam", 2]), key=str):
... print error
'spam' is not of type 'number'
'spam' is not one of [1, 2, 3]
['spam', 2] is too short
Let's construct an :class:`ErrorTree` so that we can query the errors a bit
more easily than by just iterating over the error objects.
.. code-block:: python
>>> tree = ErrorTree(v.iter_errors(instance))
As you can see, :class:`ErrorTree` takes an iterable of
:class:`ValidationError`\s when constructing a tree so you can directly pass it
the return value of a validator's ``iter_errors`` method.
:class:`ErrorTree`\s 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:
.. code-block:: python
>>> 0 in tree
True
>>> 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 ``errors`` attribute.
.. code-block:: python
>>> 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 :class:`ValidationError`\s, so
we can get at those directly if we want them.
.. code-block:: python
>>> 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 validator failed for a
given index, we check for its presence in ``errors``:
.. code-block:: python
>>> "enum" in tree[0].errors
True
>>> "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.
.. code-block:: python
>>> "minItems" in tree.errors
True
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 to the corresponding validation error.
|
