研究报告 · 约 24,710 字 · 预计推送 3 部分

数据校验与契约工程：JSON Schema、Pydantic、TypeScript Zod 与版本兼容 未开始

目录

题记与说明

报告说明：本文是课题《数据校验与契约工程：JSON Schema、Pydantic、TypeScript Zod 与版本兼容》的横纵综合报告，由两份分轴研究综合而成：纵轴（发展脉络）与横轴（横向对比，时间截面 2026-11-03）。原始检索与写作执行日为 2026-11-03，生态数据（npm/PyPI 下载量、GitHub stars、规范现状）均为当日实测快照；原文中标注"（背景知识）"或"未实测"的表述，本文保留同样标注。两份分章之间的数字口径冲突（性能倍数、兼容模式清单等）已在正文统一为"并列口径 + 注明出处与未复测"，不再各说各话。

TL;DR

从 2009 年 Kris Zyp 的首份 IETF 草案到 2026 年被塞进 LLM 工具调用热路径，数据校验走完四步：给 JSON 补一个 XSD → 规范政治与实现碎片化 → "schema 即类型"的编译期革命 → AI 时代机器对话接口。当前格局是一个三层栈：规范层 JSON Schema（2020-12 版，五年无破坏性变动，OpenAPI 3.1/3.2 已完全对齐）、库层 Pydantic v2（Python）与 Zod 4（TypeScript）、统一层 Standard Schema（由 Zod、Valibot、ArkType 三家主流库作者联合制定的可替换性规范）。三主角无一内建版本演进规则——兼容性在 JSON 生态永远靠工程补齐（Registry 兼容模式、Tolerant Reader、契约测试），Protobuf/Avro 反而在这点上领先 JSON 生态一个世代。两代重写（Pydantic v2 的 Rust 内核、Zod 4）已把主流场景的性能差距缩小到不构成迁移理由（极值场景除外），真正的护城河是 FastAPI/LangChain/MCP 的默认绑定。建议：对外契约用 JSON Schema 2020-12 + OpenAPI；Python 选 Pydantic、TS 选 Zod 4；演进问题不要指望校验库，要自建 registry 与契约测试。

纵轴：发展脉络（2009–2026）

十七年的历史可以压缩成一句话：从"给 JSON 补一个 XSD"开始，经历规范政治与实现碎片化，被"schema 即类型"的编译期革命重塑，最终在 AI 时代变成机器与世界对话的接口——而贯穿始终的主线，是"变更如何不破坏协作者"这一版本兼容问题。

时间线速览

年份JSON Schema 规范侧Python 侧TypeScript 侧契约 / 兼容生态
2009Draft 0/1（Kris Zyp，2009-12-05）———
2011–2014Draft 2/3 → Draft 4（2013-01-31，十年事实标准）jsonschema 库首发（2012-01-02）—Fowler《Tolerant Reader》（2011）；Swagger 2.0 用 JSON Schema 子集（2014，背景知识）
2015———ajv 首发（2015-05-29）；OpenAPI Initiative 成立（2015-11-05）
2016–2018Draft 5/6/7 接连发布pydantic 0.0.1（2017-05-03）—FastAPI 0.1.0（2018-12-08）
2019"2019-09"版：规范拆三文档pydantic 1.0（2019-10-23）——
20202020-12 版发布—Zod 1.0.0（2020-03-07）、TypeBox（2020-03-04）ajv 加入 OpenJS
2021——Zod 3.0.0（2021-05-17）OpenAPI 3.1.0 对齐 JSON Schema 2020-12
2022加入 OpenJS FoundationPydantic 公司化（2022-02-16）ArkType 首发（2022-09-19）"Stable Spec" ADR：规范转活文档
2023—Pydantic v2 + Rust 内核（2023-06-30）；FastAPI 0.100 双支持（2023-07-07）Valibot 首发（2023-07-12）data contract 概念运动；Bitol 筹备
2024—pydantic 2.9/2.10；Series A + Logfire + PydanticAIClerk Fellowship：Zod 全职开发OpenAI Structured Outputs（2024-08-06）；ODCS v3（2024-10）；MCP（2024-11）
20252020-12 仍为最新发布版pydantic 2.11（03）/2.12（10）Zod 4.0.0 稳定（2025-07-09）OpenAPI 3.2.0（2025-09，仍基于 2020-12）
2026规范走向"稳定基线 + vocabulary"；下一代仍为 Snapshotpydantic 2.13（04）/2.14.2（10-29，当前）；V3 开发启动官宣Zod 4.5 AOT 编译（2026-08-28）/4.6（09-09）zod 周下载 4.4 亿次；Standard Schema 被主流框架采纳

阶段一（2009–2013）：JSON 赢了，schema 是空白 —— 诞生期

背景：JSON 在 2000 年代初由 Douglas Crockford 等人推广，2006 年成为 RFC 4627，2013 年形成 ECMA-404 / RFC 8259（此段为背景知识，未单独检索）。在企业集成时代，XML 有 XSD、DTD、RelaxNG 一整套"合同语言"；REST 取代 SOAP/WSDL 的一大卖点恰恰是"轻合同"——代价是生产者与消费者之间只剩口头约定。AJAX、移动端 API 与 MongoDB 等文档数据库的爆发，让"给 JSON 一个可交换的结构描述"成为明确需求。

关键事件：

遗留的结构性问题（直接塑造了后十年的节奏）：draft-04 从未走完 IETF 的 RFC 流程，各实现自行取舍；缺少统一测试套件；验证与超媒体捆绑造成的语义混乱一直拖到 2019 年才彻底拆开。

阶段二（2011–2016）：契约的中间层与 OpenAPI 的接管 —— 生态萌芽期

驱动因素：微服务把"服务间调用的隐式假设"放大成大规模故障；平台公司达成"API-first"共识；契约从个人项目升级为行业联盟工程。

阶段三（2016–2019）：规范现代化，与两代验证库的分叉 —— 分叉期

规范侧（日期均来自 specification-links 全文抓取）：2016-10-13 Draft 5（清理版）；2017-04-21 Draft 6（新增 const、contains、布尔 schema）；2018-03-19 Draft 7（新增 if/then/else、$comment）；2019-09-17 "2019-09" 版：规范正式拆分为 Core / Validation / Hyper-Schema 三份文档，引入 vocabulary（词汇表）机制，unevaluatedProperties/unevaluatedItems 归入 Validation，超媒体路线开始边缘化。

Python 侧：

TypeScript 侧（两天的间隔预示了此后五年 TS 验证领域的根本分野——"schema 优先"还是"类型优先"）：

驱动因素：TypeScript 2.x 的 strict 模式（背景知识）让编译期类型成为主流，网络边界却仍是 any；前后端团队受够了"schema 与类型双份手工维护"的重复劳动。

阶段四（2020–2022）：对齐年 —— 收敛期

四件事把此前十年的碎片收敛到同一张坐标图上：

  1. 2020 年 12 月，JSON Schema "2020-12" 版发布（编辑 Ben Hutton）：$dynamicRef/$dynamicAnchor 取代 $recursive*，引用体系重构为 $defs/$anchor；2022-06-16 发布无功能变化的修正版。Hyper-Schema 冻结在 2019-09，再无后续——社区正式承认超媒体路线失败，规范收缩为"纯校验"。来源：specification-links。
  2. 2021 年 2 月，OpenAPI 3.1.0 发布：Schema Object 完全对齐 JSON Schema 2020-12，新增顶层 jsonSchemaDialect 字段，终结了自 2014 年以来"OpenAPI 的 schema 是魔改 draft-04、不是真 JSON Schema"的十年裂痕（历史分歧见 OAI issue #1263；特性预览见 Lorna Jane Mitchell 文章）。从此一份 JSON Schema 可以在 OpenAPI 文档、运行时校验、代码生成之间无损流通。
  3. 治理与供养问题被解决：2021-04-01 Postman 雇佣 Ben Hutton 出任 JSON Schema 规范负责人；OpenJS 于 2022-01-31 官宣接收 JSON Schema（社区申请见 json-schema-org/community#73）。
  4. 两大验证库锚定版本并各自获得供养：2021-05-17 Zod 3.0.0 发布（此后四年 TS 生态事实锚定 v3；npm API 检索）；2022-02-16 Pydantic 宣布公司化，Sequoia 领投 470 万美元种子轮（官方公告、Sequoia 合伙人文）。

此外两枚重要种子：2022-09-19 ArkType 首发（npm API 检索；运行时性能与类型推导兼得的第三极）；2022 年 11 月 json-schema-spec 仓库通过 ADR "Stable Spec"，规范从"攒一个大版本再发布"转向"稳定基线 + 增量修订的活文档"——版本号本身开始退场。

阶段五（2023–2024）：契约工程成为独立学科 —— 爆发期

Pydantic v2：一次破坏性升级的生态协调实验

TypeScript 侧：2023-07-12 Valibot 首发（npm API 检索），以按需打包、最小体积为卖点，把"校验逻辑进 bundle 的成本"变成第一性设计目标。

"数据契约"（data contract）概念运动：2022 年 Zhamak Dehghani《Data Mesh》把"数据产品应有接口契约"主流化（出版时间为背景知识）；2023 年 Andrew Jones 出版《Driving Data Quality with Data Contracts》并持续推广（andrew-jones.com）；数据契约词条进入 Wikipedia。校验从"函数入口的 if"升级为"数据生产者与消费者之间的组织级合同"。

AI 把 JSON Schema 推上热路径：

阶段六（2025–2026）：AI 时代的契约基础设施 —— 平台期与当前态

Zod 4 与"双 major 共存"的版本策略：

Pydantic 的稳定小步快跑与 V3 转向（PyPI API 检索）：2.9.0（2024-09-05）→ 2.10.0（2024-11-20）→ 2.11.0（2025-03-27）→ 2.12.0（2025-10-07）→ 2.13.0（2026-04-13）→ 2.14.0（2026-10-08）→ 2.14.2（2026-10-29，检索日最新版）。同时，官方数日前发文宣布 V3 开发启动，并说明 V1/V2 支持策略（pydantic.dev 文章）；官方 roadmap issue 明确 V3 不会复制 V2 那种大规模 API 重写（issue #10033），并可能落地 BaseStruct 实验（issue #10032）——v1→v2 的迁移之痛直接催生了 v3 的"低破坏"承诺。

JSON Schema 的"去版本化"现状：截至 2026-11-03，2020-12 仍是最新正式发布版；官方规范页把下一代只列为 "Latest Snapshot (work in progress)"（json-schema.org/specification）。演进路线是稳定基线 + vocabulary 扩展（2022-11 Stable Spec ADR、社区路线讨论 #282），而非再发一个"2025-12"。版本化的单位从"规范版本"下沉到了"词汇表"。上层生态继续加固：OpenAPI 3.2.0 已于 2025 年 9 月发布（spec.openapis.org），仍基于 2020-12；OpenAI 的 function calling/结构化输出也采用 2020-12 子集（OpenAI 社区帖）。

规模数据（会话命令输出）：zod 最近一周（2026-10-26 → 11-01）npm 下载 444,545,419 次（api.npmjs.org）；Pydantic 在 PyCon US 2024 官方页面披露月下载超 1.2 亿次（演讲者页），横轴章当日 pypistats 实测月下载 8.4 亿次。

收束：版本兼容的三条历史路线（纵轴谜底）

纵览十七年，"版本兼容"在三个不同的层被分别工程化，最终又汇合：

  1. 规范版本化路线（JSON Schema / OpenAPI 内部）：早期靠 $schema 指向元 schema URL 区分 draft；OpenAPI 3.1 引入 jsonSchemaDialect；2022 年后转向"稳定基线 + vocabulary 增量"。教训：大版本切换太贵，于是把版本颗粒度做小。
  2. 注册表演化路线（消息/流式系统）：Avro/Protobuf schema + 注册表强校验。Confluent Schema Registry（随 Confluent Platform 早期版本于约 2014–2015 年出现，首发年份来自搜索综合而非官方发行说明；见官方仓库与兼容模式文档）定义了 BACKWARD / FORWARD / FULL 及其 TRANSITIVE 传递变体、外加 NONE 的兼容模式族，默认 BACKWARD——兼容性由机器强制，而不是靠生产者的自觉（综合两份分章：纵轴列出"BACKWARD（默认）/FORWARD/FULL/NONE"，横轴另记录 adidas API Guidelines 推荐 FULL_TRANSITIVE，合并为此口径）。
  3. 语义化版本 + 宽容消费路线（库与应用层）：SemVer（Tom Preston-Werner 约 2009 年提出，2013 年定稿 2.0.0）管版本号语义；Fowler 的 Tolerant Reader 管消费者姿态。Pydantic v1→v2（2023，硬切换 + 桥接期）与 Zod v3→v4（2025，subpath 长共存）展示了这条路线的两种执行风格。

2024–2025 年后三条路线在同一张图上汇合：OpenAPI 3.1 用 JSON Schema 2020-12 描述 API，ODCS 把同一套词汇借给数据产品合同，LLM 的 Structured Outputs 与 MCP 把它们全部变成运行时强制约束。契约工程从"每个生态自己的方言"，收敛为"一个 JSON 方言 + 各语言各自的类型系统绑定"——这正是本课题三个关键词在 2026 年的真实关系。

横轴：横向对比（2026-11-03 截面）

三层生态位

"数据校验与契约工程"不是单一赛道，而是一个三层构成的栈。做对比必须先分层，否则会把"规范"和"库"、"校验"和"演进"混为一谈：

  1. 规范层（Schema as 文档/接口）：JSON Schema（含其之上的 OpenAPI）、Protobuf IDL、Apache Avro。输出是语言中立的契约文件，可被多语言消费；其中 Protobuf/Avro 把版本演进规则做进了规范本身。
  2. 运行时校验库层（Schema as 代码）：TypeScript 阵营的 Zod、Valibot、ArkType、TypeBox、Ajv、Yup；Python 阵营的 Pydantic、msgspec、marshmallow；长尾还有 TS 侧的 io-ts、runtypes、superstruct、Effect Schema 与 Python 侧的 attrs、Cerberus 等（本文不逐项展开）。输出是语言内的一等公民对象/类型，校验发生在程序运行期。
  3. 接口统一层（Schema as 协议）：TS 生态 2024–2025 兴起的 Standard Schema（由 Zod、Valibot、ArkType 三家作者联合制定，仓库），让上层框架不绑定具体校验库；以及把"代码侧 schema"翻译回"规范侧 JSON Schema"的互操作工具（Standard JSON Schema、Pydantic 的 model_json_schema、TypeBox 的天然 JSON Schema 输出）。

三个主角分别占据：JSON Schema = 规范层事实标准，Pydantic = Python 运行时校验事实标准，Zod = TypeScript 运行时校验事实标准；"版本兼容"则是贯穿三层的契约工程能力，也是各家差距最大的维度。

生态数据快照（2026-11-03 实测）

以下数字为会话内通过 api.npmjs.org、pypistats.org、api.github.com 实际拉取的结果（对端点的 HTTP GET，返回 JSON 后摘取字段）：

npm 周下载量（区间 2026-10-26 ~ 11-01；含 CI/镜像放大效应，适合看相对量级）：

包周下载量
ajv513,274,688
zod444,545,419
@sinclair/typebox164,758,993
valibot31,738,944
yup16,391,173
arktype3,150,862

PyPI 下载量（pypistats.org）：

包日周月
pydantic28,065,054260,521,987842,451,944
marshmallow1,889,42221,142,65984,070,514
msgspec776,3119,079,11529,813,196

GitHub stars（api.github.com）：

仓库StarsLicense
colinhacks/zod44,247MIT
pydantic/pydantic29,276MIT
fabian-hiller/valibot9,053MIT
arktypeio/arktype7,892MIT
sinclairzx81/typebox7,024MIT

解读：Ajv（JSON Schema 的参考执行器）与 Zod 是 TS 生态双巨头且下载量同量级；Pydantic 月下载 8.4 亿次，已属"基础设施级"依赖；挑战者梯队（Valibot/ArkType/TypeBox）stars 在 7k–9k 区间，与 Zod 差 5–6 倍，属于"已被验证、但未撼动默认选择"的位置。

运行时校验库主对比表

维度JSON Schema（经 Ajv 等执行）Pydantic v2（Python）Zod 4（TypeScript）Valibot（TS）ArkType（TS）TypeBox（TS）msgspec（Python）
形态语言中立规范 + 运行时执行器代码侧库（class + 类型注解）代码侧库（链式 API）代码侧库（函数组合）代码侧库（TS 语法字符串解析）代码侧库（JSON Schema 构建器）代码侧库（TypedDict/dataclass/Struct）
静态类型需 json-schema-to-ts 等外挂推断原生（Python 类型注解）原生推断，TS-first原生推断原生推断（声明即类型，1:1）原生推断（satisfies/static T）原生（Struct 映射 Python 类型）
性能Ajv 编译期 JIT，第一梯队Rust 内核，较 v1 加速"约 17 倍"至"5–50 倍"（口径不一，未复测）4.0 重写较 v3 快 6–15 倍（官方口径）；4.5 AOT 再快 3–9 倍适中，主打体积官方宣称比 Zod 快 50–100 倍（第三方复测有争议）编译式，第一梯队同 workload 常见 10–80 倍快于 Pydantic（社区引述）
体积/成本执行器独立于文档引入 Rust 编译轮子（pydantic-core）核心约 13 kB gzip 量级；另有 v4-mini约 1.3 kB 核心，按需 tree-shake运行时占用比 Valibot 大轻量无重依赖，C 编译轮子
JSON Schema 互操作本体即规范model_json_schema 一键导出v4 官方内建 JSON Schema 转换官方 to-json-schema 包需外挂本体就是 JSON Schema不以 JSON Schema 为中心
版本兼容原生机制无（仅 $schema 方言锚点）无内建无内建无内建无内建无内建无内建
生态位OpenAPI/文档/多语言契约的唯一公约数FastAPI/LangChain/AI 生态默认件前后端通用、MCP TS SDK 默认件客户端 bundle 敏感场景服务端性能敏感场景Fastify/JSON Schema 原生栈极致吞吐的序列化+校验一体

逐项要点

JSON Schema：规范层的事实标准，但"版本兼容"要自己造。 规范现状实测：当前版本 2020-12，上一版 2019-09，"draft next"仍在制定中（json-schema.org/specification）——规范侧五年没有破坏性变动，稳定性本身就是它对 Pydantic/Zod 的差异化优势：契约文件可以跨语言、跨年度存活。OpenAPI 3.1.0 的 Schema Object 是 2020-12 的超集（3.1.0 规范），OpenAPI 3.2.0（2025-09，规范）仍基于 2020-12。Ajv 以 5.1 亿周下载居 TS 校验类之首。版本兼容短板：规范内建的不是"数据演进规则"而是"方言锚点"（$schema）。字段增删是否破坏兼容，规范不裁决，需要 Schema Registry + 兼容模式在流程层强制。这是"契约工程"与"引入一个校验库"的本质区别所在。

Pydantic：Python 侧基础设施，V2 甜头刚吃完，V3 已经在路上。 性能口径见纵轴阶段五的统一说明（约 17 倍 vs 5–50 倍，均为二手）。竞品压力真实存在：msgspec 在不少 workload 中比 Pydantic 快 10–80 倍（taskiq #603 社区引述），且以 TypedDict/Struct 保持"零魔法"；marshmallow 月下载 8,400 万仍属老牌劲旅但增长乏力（pypistats 实测）。Pydantic 的护城河不是速度，而是 FastAPI/LLM Agent 生态的默认绑定——当 LangChain、OpenAI SDK、Vector DB 客户端都收 Pydantic 对象时，换 msgspec 的迁移成本远大于性能收益。V3 动向：官方官宣开发启动并承诺不复制 V2 式大规模 API 重写（文章、issue #10033、BaseStruct 实验 #10032）。对"版本兼容"课题而言这是教科书级案例：契约库自身的版本兼容，往往比它帮你做的数据兼容更痛。

Zod 4 与 TypeScript 挑战者：一场"三维战争"（体积、速度、生态）。 Zod 4（2025-07-09 稳定）核心重写 + Standard Schema 接口 + zod/v4-mini；Valibot 用函数组合换极致体积，核心约 1.3 kB，比 Zod 同场景小约一个数量级（Valibot 官方对比、体积实测文）；ArkType 以"TS 语法字符串"为定义载体（type("string > 5")），官方宣称比 Zod 快 50–100 倍，但第三方复测存在争议（会话内 Reddit benchmark 显示部分场景反超不成立）；TypeBox 与 JSON Schema 最亲——本体就是"用 TS 类型系统写 JSON Schema"的构建器，Fastify/OpenAPI 原生栈零摩擦；Ajv 是"规范执行器"生态位，Yup（周下载 1,639 万）是上一代表单校验王者，处于存量维护区间。挑战者们最成功的集体反击是 Standard Schema：统一校验接口规范（schema / json-schema），2025 年已被 Vercel AI SDK、MCP SDK、Inngest 等消费方采纳。洞察：当默认库太强时，挑战者的出路不是取代它，而是先把"可替换性"标准化——这对上层框架是解绑，对 Zod 是温水消解护城河。

二进制/IDL 阵营：版本兼容的"硬约束"参照系。 Protobuf proto3 官方文档 "Updating A Message Type"一节给出明确安全清单：改字段号永不安全；删除字段安全但字段号永不可复用（应 reserved 或加 OBSOLETE_ 前缀）；int32/uint32/int64/uint64/bool 彼此线格式兼容；string↔bytes 仅当 bytes 为合法 UTF-8；map 与 repeated message 二进制兼容——规范直接裁决了"什么变更可发布"。Avro 靠 writer schema / reader schema 的解析规则 + 字段默认值实现向前/向后兼容，配合 Schema Registry 的兼容模式（实践文）。对照结论：JSON Schema / Pydantic / Zod 全都没有内建演进规则——它们校验"这一版数据对不对"，不管"下一版契约还算不算数"。 在 JSON 生态里，兼容性必须靠工程实践（registry、金丝雀、契约测试、语义化版本）补齐；在 Protobuf/Avro 生态里它至少是半自动的。

版本兼容工程：横向能力矩阵

能力JSON SchemaPydanticZodProtobufAvro
版本标识$schema 方言锚点（非业务版本）无（自管）无（自管）proto 文件 + 序列化版本writer/reader schema 双轨
内建演进规则❌❌❌✅ 字段号/类型替换白名单✅ 默认值+解析规则
未知字段策略由 unevaluatedProperties 等关键字控制默认忽略（可配置禁止）默认剥离（可配置）保留未知字段（proto3）忽略或报错（可配）
官方兼容检查工具依赖第三方 registry/diff 工具无官方无官方protoc 级别保证Registry（Confluent 等）
实践兜底OpenAPI diff + 契约测试宽松默认 + deprecated 别名字段.passthrough()/宽松 schema + 契约测试规范条款即兜底兼容模式强制

适用场景决策表

场景首选理由
多语言团队/对外 API 契约JSON Schema + OpenAPI 3.1/3.2唯一语言中立公约数；3.1 起与 2020-12 完全对齐
Python Web 服务（FastAPI 栈）Pydantic v2生态默认绑定；V3 低破坏路线已官宣
Python 极致吞吐（消息解析/ETL）msgspec10–80 倍于 Pydantic 的社区引述口径（未复测），代价是生态外挂
TS 全栈/前后端通用Zod 4生态+DX+性能平衡点，AI/MCP 新生态默认件
前端 bundle 敏感Valibot约 1.3 kB 核心，比 Zod 小一个数量级
服务端性能敏感（TS）ArkType / TypeBoxArkType 宣称最快（有争议）；TypeBox 兼得 JSON Schema 原生输出
强演进 Kafka/长生命周期数据Avro + Registry，或 Protobuf兼容性规则内建于规范，JSON 侧无对等物
上层框架不想绑库（TS）实现/消费 Standard Schema三大库 + 主流框架已采纳

最小工具箱（"自建 registry 与契约测试"的具体所指）

正文建议的"自建 registry 与契约测试"落到工具上是三类组件。以下为各类公开代表（均为真实项目，本文未实测，选型请以官方文档为准）：

环节代表工具说明
Schema Registry（支持 JSON Schema）Confluent Schema Registry、Apicurio Registry消息/流式场景的兼容性强制检查点：注册时按 BACKWARD/FULL 等模式拒绝破坏性变更
契约 diff（进 CI）oasdiff、OpenAPITools/openapi-diff对 OpenAPI/JSON Schema 做版本间 diff，按兼容模式分级阻断破坏性变更
契约测试Pact（消费者驱动契约）、Schemathesis（基于 OpenAPI 的属性测试）前者验证消费方预期，后者验证提供方实现与契约一致

交叉洞察：两轴合起来说明了什么

1. 三次中心转移 + 三层共存：契约的"重力"一直在移动，但每一层都没有死。 纵轴显示重心经历了"规范（2009–2015）→ 库（2017–2022）→ AI 运行时（2024–）"三次转移；横轴则显示 2026 年的截面上三层同时健在、且在互相翻译——TypeBox 把规范变成库（本体即 JSON Schema），Pydantic/Zod 把库变回规范（导出/内建 JSON Schema 转换），Standard Schema 在库层之上再造微型规范，OpenAPI 3.1/3.2 与 ODCS 把规范词汇借给 API 与数据产品。两轴合起来的结论是：不要把任何一层判死刑。纵轴上 Hyper-Schema 是唯一被社区正式承认失败的路线（冻结于 2019-09），它死于"验证与超媒体捆绑"而非死于规范化本身；其余每一层都在被别的层重新发明。

2. 版本兼容是全场最大公约数短板，而历史早就给出了解法的三种原型。 纵轴提炼出三条路线：规范版本化（$schema → stable spec + vocabulary）、注册表强制（Confluent 兼容模式）、语义化版本 + 宽容消费（SemVer + Tolerant Reader）；横轴的能力矩阵则证明三主角无一家内建演进规则，Protobuf/Avro 反而领先 JSON 生态一个世代。两轴交叉后的关键判断是：在 JSON 生态，兼容性不是"选型问题"而是"工程建设问题"——纵轴里 Tolerant Reader（2011）与横轴里 Pydantic extra='ignore' / Zod .strip()/.passthrough() 是同一个模式的三次亮相；纵轴里 Confluent Registry 与横轴里 "OpenAPI diff + 契约测试" 的实践兜底，也是同一条原则（兼容性由机器强制，而非生产者自觉）在不同年代的表达。选哪个校验库都解决不了演进问题；能解决的是 registry、契约测试、金丝雀发布这套组合拳。

3. 库自身的 major 迁移是兼容课题的镜像案例，且两家走向了相反的修正方向。 纵轴记录了两次迁移的完整过程：Pydantic v1→v2（2023 硬切换 + FastAPI 0.100 桥接）之痛直接催生了横轴确认的 V3 官方承诺——"不复制 V2 式大规模 API 重写"；Zod v3→v4 则示范了另一种风格——zod/v4 subpath 让两个 major 在同一个包里长期共存（2025-05 的 3.25.1 已携带 v4 预览），生态逐模块迁移。横轴进一步指出挑战者打法（Standard Schema 标准化"可替换性"）与 Zod 4.5 的 AOT 编译（z.compile()）都在改变游戏规则。交叉结论：契约工程的第一课，是先解决"自己作为依赖"的兼容性，再去管"数据作为契约"的兼容性；版本颗粒度在两个方向同时下沉——规范侧从"大版本"下沉到"词汇表"，库侧从"整包 major"下沉到"subpath 双轨"。

4. 性能差距已被两代重写在主流场景缩小到不构成迁移理由（极值场景除外），真正的护城河是"默认件"位置，而 AI 正在把这个位置焊死——同时又在松动它。 横轴实测显示 Pydantic v2（约 17 倍至 5–50 倍口径）与 Zod 4（6–15 倍）的重写后，纯速度已不足以构成迁移理由；纵轴则解释了这个位置是怎么来的：FastAPI（2018）打通"类型即契约"流水线、OpenAI Structured Outputs 与 MCP（2024）把 schema 塞进热路径、LangChain 等框架默认收 Pydantic 对象。但横轴同时显示两个松动变量：Standard Schema 让上层框架可随时换库（Zod 周下载 4.4 亿但议价力在下降），msgspec/Valibot/ArkType 各守一个极值点待命。纵轴的商业供养史（Postman 雇规范负责人、Sequoia 两轮投资 Pydantic、Clerk Fellowship 供养 Zod 4）说明："默认件"地位能吸来供养，供养又巩固地位——这是正循环，但 Standard Schema 这类解绑层是唯一已知的反向力。

5. 对用户的判断与建议。 综合两轴，给出如下可执行结论：

参考来源

本综合报告的两份输入：

规范与官方文档

第三方评测、数据与讨论

未核实/未实测项汇总（承自两份分章，本文保留标注）：JSON 标准化时间线（RFC 4627/ECMA-404/RFC 8259）、Postel 定律出处 RFC 793（1980）、Swagger 2011–2014 起源与作者、TypeScript strict 模式时间、《Data Mesh》2022 年出版、ajv/Evgeny Poberezkin 与 Sebastián Ramírez 等作者署名——均标注为背景知识未单独检索；Pydantic v2 "约 17 倍/5–50 倍"、Zod 4.0 "6–15 倍"、Zod 4.5 AOT "3–9 倍"、ArkType "50–100 倍"、msgspec "10–80 倍"——均为官方宣传或二手引述，本报告未运行任何基准测试；Confluent Schema Registry 首发年份（约 2014–2015）来自搜索综合；Zod 4 beta 宣布月（2025-04）来自转述。io-ts、runtypes、superstruct、Effect Schema、attrs、Cerberus 等长尾方案仅在格局描述中带过，未做逐项实测对比。

思考题（读完后想一想，参考答案可展开）

  1. 报告断言 JSON Schema、Pydantic、Zod 三家主流方案“无一内建版本演进规则”。这一判断的依据是什么？纵轴又归纳出哪三条历史解法路线？
    参考答案

    依据是横向能力矩阵中三者“内建演进规则”全为缺失：JSON Schema 只有方言锚点，Pydantic 与 Zod 连版本标识都要自管，也无官方兼容检查工具。它们只校验“这一版数据对不对”，不裁决“下一版契约还算不算数”。纵轴归纳三条路线：规范版本化、注册表演化（如 BACKWARD、FORWARD、FULL）、语义化版本加宽容消费。可见兼容性在 JSON 生态是工程建设而非选型问题。

  2. 报告称“JSON Schema vs Zod”是伪问题。请按它的分层逻辑说明：什么契约该选哪一层、哪种方案，以及为什么性能不再构成迁移理由？
    参考答案

    两者不同层：JSON Schema 是规范层语言中立公约数，Zod 是 TS 库层默认件；真问题是契约要活几年、跨几个语言。对外多语言、长周期契约用 JSON Schema 2020-12 加 OpenAPI；Python 栈用 Pydantic v2；TS 全栈用 Zod 4；极值场景才迁移：bundle 敏感选 Valibot，吞吐选 msgspec。性能不构成理由，两代重写已缩小主流差距。

  3. 报告中大量性能数字带有“二手口径”标注。请举出至少三处口径不一或存疑的数字，并说明报告为何提醒 Zod 4.5 的 3–9 倍“不可混用”，读者应如何对待这些数字？
    参考答案

    风险集中在性能倍数与部分史实。Pydantic v2 相对 v1 有“约 17 倍”与“5–50 倍”两个口径；Zod 4.0 相对 v3 为 6–15 倍，而 4.5 的 AOT 3–9 倍是另一套基准，报告提醒“不可混用”；ArkType 宣称 50–100 倍但复测有争议。标准化时间线、Postel 定律出处等被标为背景知识。报告明言未运行任何基准测试，故这些数字只宜看量级。

  4. 报告给个人/小团队开的“最小可行契约工程”药方包含哪些组件与代表工具？它凭什么说这套组合“成本低到没有理由缺席”？
    参考答案

    个人或小团队的最小方案是：一份 JSON Schema（2020-12）作唯一事实源，各语言绑定从它生成或导出回它，CI 里跑契约 diff。工具分三类：Schema Registry 做兼容性强制检查，契约 diff 阻断破坏性变更，契约测试用 Pact 或 Schemathesis。理由是成本低到没有理由缺席；并应遵守 Tolerant Reader：生产者不删字段，消费者忽略未知字段。

← 资料库今日播报 →