jsonschema,一个标准的 Python 库

大家好，我是木木。

今天给大家分享一个数据结构校验的 Python 库，jsonschema。

jsonschema

jsonschema 是 Python 里实现 JSON Schema 规范的成熟库。它适合在 API 入参、配置文件、事件消息和跨语言数据交换处做结构校验：规则写成标准 schema，业务对象仍然可以保持普通 dict。和只靠手写 if 判断相比，它的优势是规则可复用、错误可定位，也更容易和前端、网关、文档系统共享同一份契约。

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

官方文档：https://python-jsonschema.readthedocs.io/

三大特点

标准契约

schema 本身是跨语言规范，适合前后端、服务间消息和配置文件共用。

错误清晰

iter_errors 可以收集所有问题，并能定位到具体字段路径。

版本可控

支持多种 draft，可按项目契约选择对应 validator。

最佳实践

安装方式：pip install jsonschema。如果项目已经有 JSON Schema 契约，建议把校验放在入口层，进入业务逻辑前先阻断结构不合法的数据。

第一段代码解决的问题是：用最小 schema 声明对象字段、必填项和数值边界，并验证一个合法 payload。

fromimportlib.metadataimportversionfromjsonschemaimportvalidateschema={"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer","minimum":0},},"required":["name","age"],}data={"name":"Ada","age":36}validate(data,schema)print("jsonschema:",version("jsonschema"))print("valid user:",data)

第二段代码解决的问题是：一次性收集校验错误，并把错误路径转换成可以返回给调用方的提示。

fromjsonschemaimportDraft202012Validatorschema={"type":"object","properties":{"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"enum":["admin","editor","viewer"]}},},"required":["email","roles"],}payload={"email":"ops@example.com","roles":["admin","owner"]}validator=Draft202012Validator(schema)errors=sorted(validator.iter_errors(payload),key=lambdae:list(e.path))print("error count:",len(errors))forerrorinerrors:print("path:",".".join(map(str,error.path))or"<root>")print("message:",error.message)

环境与版本信息

本文示例使用 Python 3.11.0、jsonschema 4.26.0。示例只依赖本地校验，不需要数据库或外部服务。

高级功能

jsonschema 的进阶用法不是把所有业务逻辑都塞进 schema，而是先用标准 draft 固定数据契约，再把业务规则留给服务层。这样 schema 可以稳定服务接口文档、测试夹具和消息边界。

进阶示例解决的问题是：根据 schema 里的 draft 自动选择 validator，并先检查 schema 本身是否有效。

fromjsonschema.validatorsimportvalidator_forschema={"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"enabled":{"type":"boolean","default":True},},}Validator=validator_for(schema)Validator.check_schema(schema)validator=Validator(schema)forpayloadin[{"limit":20,"enabled":True},{"limit":200}]:problems=list(validator.iter_errors(payload))print(payload,"ok"ifnotproblemselseproblems[0].message)

适用场景

适合开放 API、Webhook payload、配置文件、任务消息、跨语言系统之间的数据契约。

不适用场景

不适合需要强模型对象、复杂类型推断、自动序列化方法和 IDE 级补全的领域建模；这些场景可以考虑 Pydantic。

上线检查

1. 固定 $schema draft，不要让不同服务默认版本漂移。
2. 为必填字段、枚举、数组元素都补测试。
3. 把错误路径转换成调用方看得懂的字段名。

总结

jsonschema 胜在标准和边界清楚。它不替你设计领域模型，但很适合守住系统入口的数据契约。