JSON Schema 校验通过的八种姿势与四个真实报错
一份订单 JSON 里躺着非法邮箱、不存在的时间、五个多余字段和一个本该必填的空位,jsonschema 给出的错误数是 0。这不是配置写错一格,而是八个默认行为同时不吭声。我实际用 jsonschema 4.26.0 在 CPython 3.13.14 上跑了二十多组样本,把每一处「通过」翻出来对照官方规范原文,并把四个真实报错的报文逐字抄下来。
TL;DR:
format默认只是注解,规范要求实现方默认关闭断言;本机只注册了 8 个格式检查器,date-time不在其中,2026-13-45T99:99:99Z照样通过。properties、required、items只对自己那种实例类型生效,漏写顶层type: object时数组和字符串全部通过。multipleOf: 0.01是除法判据,9 个样本里 5 个被拒,包括 19.99。- 换 draft 更危险:
dependencies在 2020-12 下不报错也不生效,同一份 schema 两个客户端两个答案。
一、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」,漏字段合法这件事多数人知道。少人注意的是它连「这是不是对象」都不管。
实测三组:
{"properties": {"a": {"type": "integer"}}}对实例[1, 2]通过,对"hello"通过,只对{"a": "x"}报错。{"required": ["a"]}对[1, 2]通过,对"hi"通过。{"items": {"type": "integer"}}对{"a": "x"}通过。
原因不神秘:这些关键字按实例类型分派,实例不是那种类型就整段跳过,而跳过不等于失败。漏写顶层 "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") 通过。
相等判断更反直觉:
{"enum": [1]}拒绝 true,接受 1.0。{"const": 1}接受 1.0。{"uniqueItems": true}认为[1, 1.0]重复(判失败),认为[1, true]不重复(判通过)。
关键在于 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,都不是整数。
两个可用修法:
- 金额一律用最小单位整数(1999 表示 19.99),schema 写
{"type": "integer", "multipleOf": 1}。 - 保留 Decimal 实例,并把 multipleOf 也写成 Decimal:实测
Decimal("19.99")对Decimal("0.01")通过。
这一条最危险的地方在于它「看起来对」:业务方以为加了 0.01 的倍数约束就锁住了两位小数,实际是把一部分正常金额挡在门外,而被挡的往往是 19.99、0.29 这种常见价。
八、换 draft,旧关键字静默变注解
core 规范有一句「Unknown keywords SHOULD be treated as annotations」,意思是实现不认识的词就当没看见。这条在版本迁移时会变成本地无事、线上丢规则。
validation 规范附录 A 写明 dependencies 已被拆成 dependentRequired(数组形态)与 dependentSchemas(schema 形态)。于是同一份 {"dependencies": {"card": ["cvv"]}}:
- 标
$schema为 draft-07,{"card": "4111"}被拒,报文「'cvv' is a dependency of 'card'」。 - 标
$schema为 2020-12,同一个实例通过,一条警告都没有。 - 不写
$schema直接调validate(),按 2020-12 处理,通过。
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 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。