python | jsonschema，一个实用的 验证 JSON 数据结构 Python 库！

本文来源公众号“python”，仅用于学术分享，侵权删，干货满满。

原文链接：jsonschema，一个实用的 Python 库！

大家好，今天为大家分享一个实用的 Python 库 - jsonschema。

Github地址：https://github.com/python-jsonschema/jsonschema

在现代软件开发中，JSON 已经成为最常见的数据交换格式之一，无论是在 API 设计还是数据存储中，JSON 都发挥着重要的作用。然而，随着数据结构变得复杂，确保 JSON 数据的有效性和一致性变得至关重要。

jsonschema 是一个用于验证 JSON 数据结构的 Python 库，它基于 JSON Schema 标准，能够有效地定义和验证 JSON 数据的结构，从而帮助开发者避免错误并提升数据处理的可靠性。

安装

安装 jsonschema 非常简单，可以通过 pip 进行安装：

pip install jsonschema

安装完成后，就可以在项目中开始使用 jsonschema 来验证 JSON 数据的有效性。

特性

1. 支持 JSON Schema 标准：jsonschema 遵循 JSON Schema 标准，支持常见的版本（如 Draft 4、Draft 6、Draft 7 等）。

2. 复杂数据结构验证：能够验证嵌套的复杂 JSON 数据结构，包括对象、数组、字符串、布尔值等。

3. 自定义格式：支持定义自定义格式验证规则，如自定义日期格式或特定字符串模式。

4. 错误处理：在验证失败时提供详细的错误信息，帮助开发者快速定位和修复问题。

5. 灵活性高：支持扩展和自定义验证逻辑，适应不同业务场景的需求。

基本功能

1. 定义和验证基本的 JSON Schema

jsonschema 的核心功能是基于 JSON Schema 来验证数据结构。首先，需要定义一个 JSON Schema，然后使用 jsonschema 库来验证某个 JSON 数据是否符合该 Schema。

import jsonschema
from jsonschema import validate

# 定义 JSON Schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "age"]
}

# 定义待验证的 JSON 数据
data = {
    "name": "Alice",
    "age": 25
}

# 执行验证
try:
    validate(instance=data, schema=schema)
    print("JSON 数据验证通过")
except jsonschema.exceptions.ValidationError as e:
    print(f"JSON 数据验证失败: {e.message}")

在这个示例中，定义了一个基本的 JSON Schema，其中 name 字段是字符串类型，age 字段是非负整数类型，并且两个字段都是必需的。通过 validate 函数，验证 JSON 数据是否符合该 Schema。

2. 验证数组和嵌套对象

除了简单的对象类型外，jsonschema 还可以验证复杂的嵌套结构和数组数据。

# 定义包含嵌套对象和数组的 JSON Schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "children": {
            "type": "array",
            "items": {"type": "string"}
        },
        "address": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "zipcode": {"type": "string"}
            },
            "required": ["city"]
        }
    }
}

# 定义待验证的 JSON 数据
data = {
    "name": "Alice",
    "children": ["Bob", "Charlie"],
    "address": {"city": "Wonderland", "zipcode": "12345"}
}

# 执行验证
try:
    validate(instance=data, schema=schema)
    print("JSON 数据验证通过")
except jsonschema.exceptions.ValidationError as e:
    print(f"JSON 数据验证失败: {e.message}")

该示例展示了如何验证嵌套对象（address）以及数组（children）的数据结构。

3. 处理验证错误

在实际使用中，验证错误是常见的情况。jsonschema 提供了丰富的错误处理功能，能够捕获并输出详细的错误信息，帮助开发者快速发现问题。

# 定义错误的 JSON 数据
invalid_data = {
    "name": "Alice",
    "age": -5  # 年龄无效
}

# 执行验证并处理错误
try:
    validate(instance=invalid_data, schema=schema)
except jsonschema.exceptions.ValidationError as e:
    print(f"验证失败: {e.message}")
    print(f"错误路径: {e.path}")
    print(f"错误原因: {e.cause}")

当 JSON 数据不符合 Schema 时，ValidationError 异常会被抛出，开发者可以根据错误信息来调试和修复数据问题。

高级功能

1. 自定义格式验证

除了标准的类型检查外，jsonschema 还支持自定义格式验证。

例如，可以定义一个自定义的日期格式或字符串模式，并为其编写专门的验证逻辑。

from jsonschema import Draft7Validator, FormatChecker
import re

# 自定义验证日期格式
@FormatChecker.cls_checks("mydate")
def is_mydate(value):
    pattern = r"\d{4}-\d{2}-\d{2}"
    return bool(re.match(pattern, value))

# 定义 JSON Schema
schema = {
    "type": "object",
    "properties": {
        "date": {"type": "string", "format": "mydate"}
    }
}

# 定义待验证的 JSON 数据
data = {"date": "2023-10-01"}

# 执行验证
try:
    validate(instance=data, schema=schema, format_checker=FormatChecker())
    print("日期格式验证通过")
except jsonschema.exceptions.ValidationError as e:
    print(f"日期格式验证失败: {e.message}")

这个例子展示了如何定义一个自定义的日期格式，并将其集成到 JSON Schema 的验证过程中。

2. 自定义验证器

jsonschema 允许你扩展其验证机制，创建自定义的验证器以处理特定的验证需求。

from jsonschema import Draft7Validator, ValidationError

# 自定义验证函数，确保 "age" 字段大于 18
def validate_age(validator, age, instance, schema):
    if age == "age" and instance < 18:
        yield ValidationError(f"{instance} 不符合年龄要求")

# 创建自定义验证器
validator = Draft7Validator(schema)
validator.VALIDATORS["age"] = validate_age

# 定义待验证的 JSON 数据
data = {"name": "Alice", "age": 15}

# 执行验证
errors = sorted(validator.iter_errors(data), key=lambda e: e.path)
for error in errors:
    print(error.message)

这个示例展示了如何创建自定义的验证规则，确保某个字段符合特定的业务逻辑。

总结

Python jsonschema 是一个功能强大且灵活的工具，能够帮助开发者定义和验证 JSON 数据的结构。通过使用 JSON Schema，开发者可以确保数据的有效性和一致性，减少代码中的错误，并提升数据处理的可靠性。无论是验证 API 请求、配置文件，还是复杂的嵌套数据结构，jsonschema 都为开发者提供了一个高效的解决方案。

THE END !

文章结束，感谢阅读。您的点赞，收藏，评论是我继续更新的动力。大家有推荐的公众号可以评论区留言，共同学习，一起进步。