Julian/jsonschema 项目：JSON Schema 验证完全指南

Julian/jsonschema 项目：JSON Schema 验证完全指南

jsonschema 项目地址: https://gitcode.com/gh_mirrors/jso/jsonschema

前言

JSON Schema 是一种强大的工具，用于描述和验证 JSON 数据的结构。Julian/jsonschema 是一个 Python 实现，提供了完整的 JSON Schema 规范支持。本文将深入解析该库的核心验证功能，帮助开发者掌握 JSON 数据验证的方方面面。

基础验证

最简单的验证方式是使用 validate() 函数：

from jsonschema import validate

# 基本验证示例
schema = {"type": "string"}
validate("hello", schema)  # 验证通过
validate(42, schema)       # 抛出 ValidationError

validate() 函数接受三个主要参数：

• instance: 要验证的 JSON 数据
• schema: 使用的 JSON Schema
• cls: 指定验证器类（默认为最新规范版本）

验证器协议

jsonschema 定义了一个验证器协议（Validator Protocol），所有验证器类都必须遵循这个协议。理解这个协议对于高级用法至关重要。

核心协议方法包括：

• is_valid(instance): 返回布尔值表示验证结果
• iter_errors(instance): 生成所有验证错误
• validate(instance): 验证并抛出第一个发现的错误

from jsonschema import Draft202012Validator

validator = Draft202012Validator({"type": "number"})
validator.is_valid(42)  # True
validator.is_valid("42")  # False

类型检查机制

JSON Schema 的 type 关键字由 TypeChecker 处理。默认情况下：

• number 检查 numbers.Number
• integer 检查 int（不是 numbers.Integral）
• object 检查 dict（不是 collections.abc.Mapping）

这种设计在通用性和性能之间取得了平衡。

自定义类型检查

你可以扩展或修改类型检查：

from jsonschema import Draft202012Validator, validators

def is_my_number(checker, instance):
    return isinstance(instance, (int, float, MyCustomNumber))

type_checker = Draft202012Validator.TYPE_CHECKER.redefine(
    "number", is_my_number
)

CustomValidator = validators.extend(
    Draft202012Validator,
    type_checker=type_checker
)

版本化验证器

jsonschema 支持多个 JSON Schema 规范版本：

• Draft202012Validator (最新)
• Draft201909Validator
• Draft7Validator
• Draft6Validator
• Draft4Validator
• Draft3Validator

每个验证器类都实现了相同的 Validator 协议，但支持各自版本的规范特性。

from jsonschema import Draft202012Validator

schema = {
    "$schema": Draft202012Validator.META_SCHEMA["$id"],
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"}
    },
    "required": ["email"]
}

Draft202012Validator.check_schema(schema)  # 验证schema本身是否有效

格式验证

JSON Schema 的 format 关键字可以验证字符串、数字等基本类型是否符合特定格式。默认情况下，格式验证是可选的。

启用格式验证

from jsonschema import validate, Draft202012Validator

# 不验证格式
validate("not-an-ip", {"format": "ipv4"})  # 通过

# 启用格式验证
validate(
    "not-an-ip",
    {"format": "ipv4"},
    format_checker=Draft202012Validator.FORMAT_CHECKER
)  # 抛出 ValidationError

支持的格式

jsonschema 支持多种格式验证，部分需要额外依赖：

| 格式 | 依赖 | 说明 | |------|------|------| | color | webcolors | CSS颜色值 | | date-time | rfc3339-validator | RFC3339日期时间 | | email | 无 | 基本电子邮件验证 | | hostname | fqdn | 主机名验证 | | ipv4/ipv6 | 无 | IP地址验证 | | uri | rfc3986-validator | URI验证 |

建议通过 extras 安装格式依赖：

pip install jsonschema[format]       # 包含GPL依赖
pip install jsonschema[format-nongpl] # 非GPL替代

自定义格式验证

from jsonschema import FormatChecker

format_checker = FormatChecker()

@format_checker.checks("even-number")
def is_even(instance):
    return instance % 2 == 0

schema = {"format": "even-number"}
validate(4, schema, format_checker=format_checker)  # 通过
validate(3, schema, format_checker=format_checker)  # 失败

最佳实践

1. 明确指定规范版本：始终在 schema 中使用 $schema 关键字
2. 重用验证器实例：创建验证器实例比每次都新建更高效
3. 谨慎使用格式验证：了解不同规范版本间的格式差异
4. 处理验证错误：使用 iter_errors() 获取所有错误而非仅第一个

validator = Draft202012Validator(schema)
errors = list(validator.iter_errors(instance))
if errors:
    for error in errors:
        print(f"错误路径: {error.path}")
        print(f"错误信息: {error.message}")

通过掌握这些核心概念，你将能够充分利用 jsonschema 进行复杂的数据验证工作。

jsonschema 项目地址: https://gitcode.com/gh_mirrors/jso/jsonschema