JSON Schema $ref：definitions / $defs 与模块化复用

一、为什么要 $ref

一个 API 里 User 类型往往在多个响应、多个嵌套位置重复出现。内联复制会导致「改一处、漏一处」。把 User 抽成一个具名定义，各处用指针引用， 结构就只有一份真相。draft-07 习惯放在 definitions，较新草案用 $defs，站内工具两者都支持。

二、带 $ref 的 Schema 示例

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user": { "$ref": "#/definitions/User" }
  },
  "definitions": {
    "User": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string", "enum": ["admin", "member"] }
      },
      "required": ["id", "email"]
    }
  }
}

生成示例时会沿指针找到 User 并展开，得到形如 { "user": { "id": 0, "email": "user@example.com", "role": "admin" } } 的结果（email 采用 format 占位值，role 取 enum 首项）。

三、指针与转义：~0 / ~1

$ref 的值是一个 JSON Pointer，用 / 分隔层级。因为 / 与 ~ 在路径里有特殊含义，键名中出现它们时必须转义：

• 键名含 / → 写作 ~1，例如属性 "a/b" 引用为 #/properties/a~1b。
• 键名含 ~ → 写作 ~0。
• 解析顺序是先 ~1 再 ~0，否则 ~01 会被误读。

四、循环引用：递归栈保护

递归结构（例如评论里再嵌评论）会让 Schema 引用自身。生成示例时若不加保护就会无限展开。站内工具的规则是： 第二次进入同一个 $ref 立即返回 null，终止递归。因此像 #/definitions/Node 引用自身的结构也能安全产出示例，深层节点以 null 占位。

注意：只有本地指针（# 开头）才做解析与循环保护；外部 URL 引用不拉取，直接 null 占位。

五、组合关键字与整数、浮点的合并

• allOf 合并。各分支结果合并：对象取属性并集（先出现的键优先保留），数组拼接（最多 5 个元素），叶子取首个非 null；自身除组合关键字外的其它约束会一同参与，不丢 title 之类声明。
• oneOf / anyOf 取首个。生成示例时取第一个对象分支；要看到其它分支只好手工调整顺序或替换成具体子 Schema。
• $ref 与兄弟关键字。draft-07 中 $ref 与相邻关键字的行为有历史争议，站内工具的做法是：见到 $ref 即以被引用目标为准生成，不额外合并同级约束。

六、两种 items：tuple 与 list

数组的 items 有两种写法，语义完全不同：

• items 为对象（list）。所有元素同型，生成时按 minItems 补足数量（上限 5 个），默认 1 个。
• items 为数组（tuple）。逐位置对应不同类型，生成时按数组逐项展开（最多 5 项），适合固定长度、位置有语义的结构。
• 空 items（{}）会生成 [{}]，因为无从得知元素形状。

七、常见错误

• 用外部 URL 引用。纯前端不做网络拉取，跨文件引用会得到 null；请把目标定义合并进同一文档，或改用 $defs 本地化。
• 指针层级写错。#/definitions/User 里的 definitions 是真实键名，改过存放位置后引用要同步更新。
• 忘记转义。键名含 / 或 ~ 时未用 ~1 / ~0，会解析失败。
• 指望循环引用全展开。递归结构第二次进入即 null，需要完整样例请手工替换深层节点。
• tuple 与 list 混用。items 既想表达「固定位置类型」又想表达「统一元素类型」会语义冲突，按场景二选一。