jsonschema-pyref

此软件包为jsonschema的RefResolver添加了对通过两种新的自定义URL方案解析模式$ref的支持

• py-obj：使用此方案的URL允许从Python模块/类等中的dict加载模式。这使用点属性表示法表示模式的路径。例如，py-obj:package.submodule.Class.schema解析为模块package.submodule中类Class的schema类属性。

• py-pkgdata：使用此方案的URL允许从与Python包一起安装的包数据文件（目前仅支持JSON和YAML）加载模式。例如，py-pkgdata:package.subpackage/schema.json从安装包的任何位置加载package/subpackage下的schema.json文件。

许多JSON模式有一个$id属性声明模式的唯一身份。通常这是一个http(s) URL，但没有任何要求它必须是。通常这只是为了命名空间，并且提供的URL在技术上不需要存在。

在实际中，如果你的Python包附带了一些由包使用的模式，并且你想从另一个包或其他相同包中的其他模式引用这些模式，那么用于模式$id的http方案对此没有帮助。有必要在模式$id中的URL和它们在Python包中的实际位置之间提供某种映射。

使用这些自定义URL方案意味着该方案的主目录位于Python包或模块中（如果方案是在Python代码中直接声明的），并且它不在网络资源上。

这为声明与Python代码一起安装的schema的$id和$ref提供了一种替代方法。

示例

>>> import jsonschema
>>> from jsonschema_pyref import RefResolver
>>> schema = {
...     'properties': {
...         'a': {'$ref': 'py-obj:jsonschema_pyref.examples.schema1'},
...         'b': {'$ref': 'py-pkgdata:jsonschema_pyref.examples/schema1.json'},
...         'c': {'$ref': 'py-pkgdata:jsonschema_pyref.examples/schema2.yml'}
...      }
... }
>>> resolver = RefResolver.from_schema(schema)
>>> doc = {'a': 'hello', 'b': 'world', 'c': 123}
>>> jsonschema.validate(doc, schema, resolver=resolver) is None
True

作为便利，还提供了jsonschema_pyref.validate作为jsonschema.validate的替换，默认使用自定义的RefResolver

>>> from jsonschema_pyref import validate
>>> validate(doc, schema) is None
True

让我们看一下引用的schema中有什么，以了解我们正在对文档进行哪些验证

>>> from pkgutil import get_data
>>> import jsonschema_pyref.examples
>>> jsonschema_pyref.examples.schema1
{'type': 'string'}
>>> def show_file(filename):
...     data = get_data('jsonschema_pyref.examples', filename)
...     print(data.decode('ascii').strip())
...
>>> show_file('schema1.json')
{"type": "string"}
>>> show_file('schema2.yml')
type: integer

这些示例schema可能很简单，但你可以轻松地确认，这同样适用于更复杂的schema。

为了证明确实加载了正确的schema（并且文档不仅仅是被简单验证），我们还可以尝试一些反例

>>> doc1 = dict(doc, a=123)
>>> jsonschema.validate(doc1, schema, resolver=resolver)
Traceback (most recent call last):
...
jsonschema.exceptions.ValidationError: 123 is not of type 'string'
...
Failed validating 'type' in schema['properties']['a']:
    {'type': 'string'}
...
On instance['a']:
    123

>>> doc2 = dict(doc, b=123)
>>> jsonschema.validate(doc2, schema, resolver=resolver)
Traceback (most recent call last):
...
jsonschema.exceptions.ValidationError: 123 is not of type 'string'
...
Failed validating 'type' in schema['properties']['b']:
    {'type': 'string'}
...
On instance['b']:
    123

>>> doc3 = dict(doc, c='hello')
>>> jsonschema.validate(doc3, schema, resolver=resolver)
Traceback (most recent call last):
...
jsonschema.exceptions.ValidationError: 'hello' is not of type 'integer'
...
Failed validating 'type' in schema['properties']['c']:
    {'type': 'integer'}
...
On instance['c']:
    'hello'

以下是一个稍微复杂一些的示例，演示了相对引用如何与py-pkgdata URLs一起工作，以及片段是如何相对于每个schema正确解析的。

首先是我们有schema4.yml，它也包含一个$id属性，允许jsonschema.RefResolver正确确定相对引用（如{"$ref": "schema3.json"}）的基URL

>>> show_file('schema4.yml')
$id: "py-pkgdata:jsonschema_pyref.examples/schema4.yml"
type: "object"
properties:
    foo: {"$ref": "schema3.json"}
    bar: {"$ref": "#/$defs/bar"}
additionalProperties: false
$defs:
    bar: {"type": "integer"}

以及schema3.json

>>> show_file('schema3.json')
{
    "$id": "py-pkgdata:jsonschema_pyref.examples/schema3.json",
    "type": "object",
    "properties": {
        "foo": {"$ref": "#/$defs/foo"}
    },
    "additionalProperties": false,
    "$defs": {
        "foo": {"type": "string"}
    }
}

这是一个应该针对schema4进行验证的文档，我们也将通过$ref加载它

>>> doc = {
...     'foo': {'foo': 'hello'},
...     'bar': 123
... }
...
>>> schema = {'$ref': 'py-pkgdata:jsonschema_pyref.examples/schema4.yml'}
>>> resolver = RefResolver.from_schema(schema)
>>> jsonschema.validate(doc, schema, resolver=resolver) is None
True

以及一些反例

>>> doc1 = dict(doc, foo={'foo': 123})
>>> jsonschema.validate(doc1, schema, resolver=resolver)
Traceback (most recent call last):
...
jsonschema.exceptions.ValidationError: 123 is not of type 'string'
...
Failed validating 'type' in schema['properties']['foo']['properties']['foo']:
    {'type': 'string'}
...
On instance['foo']['foo']:
    123

>>> doc2 = dict(doc, bar='bar')
>>> jsonschema.validate(doc2, schema, resolver=resolver)
Traceback (most recent call last):
...
jsonschema.exceptions.ValidationError: 'bar' is not of type 'integer'
...
Failed validating 'type' in schema['properties']['bar']:
    {'type': 'integer'}
...
On instance['bar']:
    'bar'

API文档

https://jsonschema-pyref.readthedocs.io/zh/latest/api.html