关于JSON Schema层级定义及自定义顶级键的可行性咨询

1. definitions 是JSON Schema的标准关键字吗？ #

没错，definitions 是JSON Schema从Draft 04到Draft 2020-12版本里的标准关键字，就是用来存放可复用的Schema片段的。你可以用 $ref 关键字引用这里面的内容，举个例子：

{
  "definitions": {
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "properties": {
    "userEmail": { "$ref": "#/definitions/email" }
  }
}

另外，Draft 2019-09及之后的版本还新增了 $defs 关键字，功能和 definitions 完全一致，是官方更推荐的新写法。

2. 自定义顶级键（比如formats）可行吗？ #

完全可以自定义顶级键，JSON Schema允许添加任何非标准的自定义关键字——标准验证器会直接忽略这些未被官方定义的关键字，不会影响Schema的核心验证逻辑。但要注意两点：

• 如果你想让这些自定义的"formats"被验证器识别并执行验证规则，这种方式行不通。标准验证器只会处理官方定义的format关键字（比如email、date-time这类）。如果需要实现自定义验证逻辑，应该用pattern、allOf、if/then/else这些标准关键字，或者自行扩展验证器的自定义格式支持。
• 如果你只是把formats作为内部管理复用片段的分组，这种做法没问题，但从规范性和可读性来说，更推荐用官方的definitions（或$defs）来存放可复用的Schema，其他熟悉JSON Schema的开发者能一眼看懂结构。

3. 是否需要把所有内容都放在definitions下？ #

不需要。definitions只是用来存放需要重复引用的片段，Schema的核心验证逻辑（比如properties、type、required这些）直接放在顶级层级即可，只有那些要多次用到的部分才放进definitions，这样Schema结构会更清晰。

内容的提问来源于stack exchange，提问作者tok