← 返回首页

JSON Schema 校验通过的八种姿势与四个真实报错

PythonJSON Schema数据校验

一份订单 JSON 里躺着非法邮箱、不存在的时间、五个多余字段和一个本该必填的空位,jsonschema 给出的错误数是 0。这不是配置写错一格,而是八个默认行为同时不吭声。我实际用 jsonschema 4.26.0 在 CPython 3.13.14 上跑了二十多组样本,把每一处「通过」翻出来对照官方规范原文,并把四个真实报错的报文逐字抄下来。

TL;DR:

// FLOW_01一条数据从 JSON 到入库要过四道闸5 NODES01STEP_01原始 JSON02STEP_02type 与 required 结构断言03STEP_03enum 与 format 值断言04STEP_04draft 方言核对05STEP_05入库前业务二次校验END_OF_FLOW
一条数据从 JSON 到入库要过四道闸 · 依据本文步骤自绘示意图
JSON Schema 校验的四道闸示意
JSON Schema 校验的四道闸示意 · 依据本文主题生成的示意图
PythonJson
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

一、format 是注解,默认不做断言

官方类型文档的原话是「By default, format is just an annotation and does not affect validation」。validation 规范 §7.2.1 更硬气:「The implementation MUST provide options to enable and disable such evaluation and MUST be disabled by default」。关掉是规范强制,打开才是可选。

实测五个字符串,在默认路径下 is_valid 全部为真:not-an-email、a@b、x y@example.com、@@、空串。挂上 format_checker 之后,not-an-email 与空串被拒,但 a@b 和 @@ 仍然通过。官方 FAQ 自己写了原因:email 只提供 sanity check,不是完整的 RFC 5322 校验。

更隐蔽的是检查器本身不全。本机只装了 jsonschema 本体,FORMAT_CHECKER.checkers 里只有 8 个键:date、email、idn-email、idn-hostname、ipv4、ipv6、regex、uuid。date-time、hostname、uri、duration、json-pointer 一个都没有,因为它们各自依赖额外包(rfc3339-validator、fqdn、rfc3987、isoduration、jsonpointer)。官方文档把后果写明:「If a dependency is not installed when using a checker that requires it, validation will succeed without throwing an error」。

format本机是否注册非法样本结果
date是2026-02-30被拒
ipv4是999.1.1.1被拒
uuid是not-uuid被拒
date-time否2026-13-45T99:99:99Z通过
hostname否@@ bad host @@通过
uri否not a uri通过

同一份 schema、同一个校验器,差别不在你的规则写得好不好,而在哪几个检查器真的装上了。要么装 jsonschema[format],要么别把 format 当类型校验用,要么自己拿 FormatChecker.checks 补。

二、properties 不是类型断言

官方文档有一句「By default, leaving out properties is valid」,漏字段合法这件事多数人知道。少人注意的是它连「这是不是对象」都不管。

实测三组:

原因不神秘:这些关键字按实例类型分派,实例不是那种类型就整段跳过,而跳过不等于失败。漏写顶层 "type": "object",你写的所有字段规则只在一个恰好是 dict 的实例上生效。

对照实测更直观:8 个字段全填错的 dict 得到 8 条错误;同一批数据换成 list 送去校验,0 条。一条 schema 里最值钱的不是 required,是第一行的 type。

三、additionalProperties 默认放行,而且只认同一层

官方原文「By default any additional properties are allowed」。给一份只声明 id 的 schema 塞 5 个多余键,默认路径 0 条错误;改成 "additionalProperties": false 之后是 1 条错误,报文把所有键名一次列完:「Additional properties are not allowed ('extra_a', 'extra_b', 'extra_c', 'extra_d', 'extra_e' were unexpected)」。注意是 1 条不是 5 条 —— 按错误条数估「多余字段有几个」必然估错。

第二个坑在复用。官方文档另有一句:「additionalProperties only recognizes properties declared in the same subschema as itself」。实测把基础字段放进 $defs,用 allOf 加 $ref 引入,外层再写 additionalProperties: false:本意是拦住多余键,实际连 id 都被判成多余的,报文是「Additional properties are not allowed ('id' was unexpected)」。规则写在 A 处、生效范围只在 A 处,拼装之后就错位了。

正解是 unevaluatedProperties(draft 2019-09 起)。它能看见子 schema 里声明过的属性,官方描述是「similar to additionalProperties except that it can recognize properties declared in subschemas」。同一结构换成 unevaluatedProperties: false,id 通过、nope 被拒,符合预期。

四、校验器不改你的数据

官方 FAQ 的标题就是这个疑问,答案第一句:「The basic answer is that the specification does not require that default actually do anything」。紧接着还有一句更狠的:让 default 去改实例,会出现「第一次校验通过、第二次失败」的情况。

实测:schema 里写 "retries": {"type": "integer", "default": 3},送去 {},validate() 正常返回,dict 仍是 {},"retries" in data 为 False。想要默认值只有两条路:自己 setdefault,或按 FAQ 给的 validators.extend 写一个会填默认值的校验器类。

第二件事是字段存在性。{"type": "object", "properties": {"amount": {"type": "number"}}} 对 {} 通过,通过之后下游一句 data["amount"] 直接抛 KeyError('amount')。required 只看键在不在,值是不是 null 它不管:{"required": ["token"]} 对 {"token": null} 通过。

所以一条字段规则要写两遍:properties 里定类型,required 里定存在。少写后者,校验器给的是绿灯,生产给的是 500。

五、数值口径:1.0 是 integer,true 不是

validation 规范 §6.1.1 的定义是「integer which matches any number with a zero fractional part」,判据是小数部分为零,不是「字面上没有小数点」。官方类型页脚注也写了:「JSON does not have separate types for integer and floating-point」。

实测 {"type": "integer"}:1 通过、1.0 通过、0.0 通过、1e3 通过;1.5 被拒、"1" 被拒、true 被拒、false 被拒、Decimal("1") 被拒。

{"type": "number"}:true 与 false 仍被拒,Decimal("1") 通过。

相等判断更反直觉:

关键在于 JSON 的相等和 Python 的相等不是一回事,而且方向正好相反:Python 里 1 == True 为真,校验器当两个不同的值;Python 里 1 == 1.0 也为真,校验器同样当同一个值。两条都「反着记」的人,会同时写错布尔开关和金额去重。

工程含义很直接:布尔字段必须写 "type": "boolean",别用 0/1 兼做开关;金额别用 float 表示。

六、oneOf 双命中是失败

三选一的类型字段最容易踩。oneOf 要求恰好一个分支成立,两个分支都成立就整体失败。

实测两个分支分别 required a 与 required b,实例 {"a": 1, "b": 2} 两个都满足,oneOf 不通过,报文是「{'a': 1, 'b': 2} is valid under each of {'type': 'object', 'required': ['b']}, {'type': 'object', 'required': ['a']}」。同一份分支换成 anyOf 则通过。

报文里有两个细节会误导人:分支顺序被反了(先 b 后 a,不是声明顺序),以及整个实例被 repr 进字符串(生产日志里可能带出敏感字段)。看到这条报文先查「是不是两个分支都松」,别去改数据类型。

七、multipleOf 是除法判据

规范原文:「A numeric instance is valid only if division by this keyword's value results in an integer」。判据是除法结果,不是「小数点后几位」。

{"multipleOf": 0.01} 实测 9 个样本,5 个被拒(55.6%):0.02 通过、0.03 通过、0.1 通过、100.0 通过;0.07 被拒、19.99 被拒、0.1+0.2 被拒、2.675 被拒、1.13 被拒。原因可以直接算出来:0.07/0.01 = 7.000000000000001,19.99/0.01 = 1998.9999999999998,都不是整数。

两个可用修法:

这一条最危险的地方在于它「看起来对」:业务方以为加了 0.01 的倍数约束就锁住了两位小数,实际是把一部分正常金额挡在门外,而被挡的往往是 19.99、0.29 这种常见价。

八、换 draft,旧关键字静默变注解

core 规范有一句「Unknown keywords SHOULD be treated as annotations」,意思是实现不认识的词就当没看见。这条在版本迁移时会变成本地无事、线上丢规则。

validation 规范附录 A 写明 dependencies 已被拆成 dependentRequired(数组形态)与 dependentSchemas(schema 形态)。于是同一份 {"dependencies": {"card": ["cvv"]}}:

items 的数组形态更能说明问题:draft-07 下 check_schema 通过,2020-12 下抛 SchemaError: [{'type': 'string'}, {'type': 'integer'}] is not of type 'object', 'boolean'。同一份 schema 在两个 draft 下,一个是合法输入、一个是非法输入。

所以 $schema 不是装饰行:把它写死,并确认服务端与客户端选的是同一版。跨语言调用时尤其要查对方实现支持到哪一版。

排错:四个真实报错与它们没告诉你的事

报错一:SchemaError: 'strng' is not valid under any of the given schemas

这是 type 拼错。报文只说「值不合法」,不说是哪个关键字、合法值有哪些。修法是先跑 Validator.check_schema(schema) 再校验,并把合法类型名从 META_SCHEMA 里取出来对照,别凭记忆拼。

报错二:_WrappedReferencingError: PointerToNowhere: '/$defs/nope' does not exist within {'$ref': '#/$defs/nope'}

$ref 指向不存在的键。注意 within 后面打印的是整份 schema,不是 $defs 那一节,很容易看错对象。修法是核 $defs 的键名与 #/ 路径拼写,尤其别漏掉 #。

报错三:ValidationError: 'a' is a required property

报文看着清楚,但它不带位置:根层对象的 path 是空列表。嵌套时要用 absolute_path 或 json_path,实测一段嵌套数据得到 $.items[1].sku。日志里别拼 str(error),拼路径。

报错四(假报错):Additional properties are not allowed ('id' was unexpected)

id 明明写在 $ref 的基础 schema 里,却仍被判多余。这是第三节的 allOf 结构问题,不是数据问题。改 unevaluatedProperties,不要去改数据。

FAQ

Q:只写 required,不写 type: object 行不行?

不行。required 只对对象实例生效,数组和字符串会整段跳过,等于没校验。

Q:format: date-time 是不是永远不会报错?

在只装 jsonschema 本体的情况下是。date-time 需要 rfc3339-validator,缺依赖时官方文档明写「validation will succeed without throwing an error」。

Q:金额字段用 multipleOf: 0.01 行不行?

不行,19.99 会被拒。用最小单位整数,或 Decimal 实例配 Decimal 的 multipleOf。

Q:装上 jsonschema[format] 就完全可靠了吗?

不是。email 仍只是 sanity check,@@ 照样通过;真要卡口径得自己拿 FormatChecker.checks 写检查器。

结语

八个「通过」里,只有两个能靠 code review 抓出来:漏写 type、漏写 required。其余六个都藏在默认值和 draft 版本里,看代码看不出来,只有跑样本才现形。校验器通过只代表「没有违反你写下的规则」,不代表数据能进库。

实操层面的三件事值得写进项目约定:schema 顶层 $schema 写死并统一;format 依赖显式装齐,或干脆不用 format;金额统一用最小单位整数。

需要说明边界:本文只测了 Python 的 jsonschema 4.26.0,没有对比 ajv、hyperjump 这类 JavaScript 实现,跨实现差异要另测;unevaluatedProperties 只在 2020-12 下跑过,2019-09 未单独验证;format 只剩 8 个检查器是「只装本体、不装 extras」的结果,装齐依赖后数量会变,但缺依赖时静默通过这条行为不变。

这条线上的相邻问题我写过几篇:金额舍入那篇 讲 round、Decimal 与 float 的三套口径,可与本篇的 multipleOf 对照着看;配置解析那篇 讲 YAML 1.1 与 1.2 把同一行字面量解析成不同类型;命令行解析那篇 讲参数在落到 Namespace 之前丢在哪一步。三篇合起来是同一条线:输入进程序之前,值已经不是你以为的那个值。

本文不含任何联盟推广链接,也没有 Amazon 商品推荐,所有数字都来自本机实测与官方文档原文。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页