バリデーションエラーのハンドリング

無効なインスタンスが発生した場合、: exc: ‘ValidationError’ が発生または返されると、メソッドまたは関数を使用するに応じて。

exception jsonschema.exceptions.ValidationError(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)[ソース]

インスタンスを提供されたスキーマの下で正しく検証しなかった。

エラーによって伝えられる情報を大まかに分解:

症状

発生理由

バリデーション対象
message

context

cause

instance

path

schema

schema_path

validator

validator_value
message

人が読みやすいエラーの説明。

validator

The failed validator.

validator_value

スキーマによりバリデーションにひっかかった値。

schema

The full schema that this error came from. This is potentially a subschema from within the schema that was passed into the validator, or even an entirely different schema if a $ref was followed.

relative_schema_path

collections.deque はスキーマ内で失敗したバリデータへのパスを含んでいます。

absolute_schema_path

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, not schema).

schema_path

relative_schema_path と同じ。

relative_path

A collections.deque containing the path to the offending element within the instance. The deque can be empty if the error happened at the root of the instance.

absolute_path

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, not instance). The deque can be empty if the error happened at the root of the instance.

path

relative_path と同じ.

instance

The instance that was being validated. This will differ from the instance originally passed into validate if the validator 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.

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.

cause

If the error was caused by a non-validation error, the exception object will be here. Currently this is only used for the exception raised by a failed format checker in FormatChecker.check().

parent

A validation error which this error is the context of. None if there wasn’t one.

無効なスキーマが検出された場合 SchemaError が送出されます。

exception jsonschema.exceptions.SchemaError(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)[ソース]

提供されたスキーマが不正な形式です。

同じアトリビュートが ValidationError 用に存在しています。

これらのアトリビュートは短い使用例で明確に出来ます。

schema = {
    "items": {
        "anyOf": [
            {"type": "string", "maxLength": 2},
            {"type": "integer", "minimum": 5}
        ]
    }
}
instance = [{}, 3, "foo"]
v = Draft4Validator(schema)
errors = sorted(v.iter_errors(instance), key=lambda e: e.path)

このシチュエーションでのエラーメッセージは自分自身には全く役に立ちません。

for error in errors:
    print(error.message)

出力:

{} 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.

for error in errors:
    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.

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'

エラーの文字列表現は、デバッグを容易にこれらの属性のいくつかを兼ね備えています。

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

エラーツリー

インスタンスの検証時にプロパティや失敗したバリデータを問い合わせるようにプログラミングしたいなら、おそらく ErrorTree を使ってみたくなると思います。

class jsonschema.validators.ErrorTree(errors=())

ErrorTrees ではどの検証が失敗したを確認するのが容易になりました。

errors

The mapping of validator names to the error objects (usually ValidationErrors) at this level of the tree.

__contains__(index)

instance[index] がエラーかどうかを確認してください。

__getitem__(index)

“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.

__iter__()

エラーが発生したインスタンスのインデックスをイテレート(ただし再帰的にではない)します。

__len__()

total_errors と同じです.

total_errors

子要素を含むエラーツリー全体の総数です。

次の例を考えてみます。

schema = {
    "type" : "array",
    "items" : {"type" : "number", "enum" : [1, 2, 3]},
    "minItems" : 3,
}
instance = ["spam", 2]

明快さのために、特定のインスタンスはこのスキーマの下で 3 つのエラーがあります。

v = Draft3Validator(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 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’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:

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

>>> 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 validator failed for a given index, we check for its presence in errors:

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

>>> "minItems" in tree.errors
True

エラーのツリーを扱うために知っておくべき全てです。

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.

best_match と関連性

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 Draft4Validator
>>> from jsonschema.exceptions import best_match

>>> schema = {
...     "type": "array",
...     "minItems": 3,
... }
>>> print(best_match(Draft4Validator(schema).iter_errors(11)).message)
11 is not of type 'array'
jsonschema.exceptions.best_match(errors, key=<function relevance at 0x7ffc85a3d938>)[ソース]

与えられた誤差の内一番マッチすると思われるエラーを検索します。

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.

パラメタ:
  • 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.
戻り値:

一番マッチしたエラーか、またはイテレータが空の時は None

ノート

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)

ヒューリスティックな関連性に基づいてエラーをソートできるkey関数です。

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.

>>> schema = {
...     "properties": {
...         "name": {"type": "string"},
...         "phones": {
...             "properties": {
...                 "home": {"type": "string"}
...             },
...         },
...     },
... }
>>> instance = {"name": 123, "phones": {"home": [123]}}
>>> errors = Draft4Validator(schema).iter_errors(instance)
>>> [
...     e.path[-1]
...     for e in sorted(errors, key=exceptions.relevance)
... ]
['home', 'name']
jsonschema.exceptions.by_relevance(weak=frozenset(['oneOf', 'anyOf']), strong=frozenset([]))[ソース]

関連度順にエラーをソートするために使用できるkey関数を作成します。

パラメタ:
  • weak (set) – a collection of validators 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 validators, 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) – 「strong」であると考慮すべきバリデータのコレクション