ToolVault

现象：校验不通过，报错指向 required

你拿一段 JSON 去校验，Schema 返回类似：

{
  "keyword": "required",
  "message": "should have required property 'email'",
  "missingProperty": "email"
}

意思是：Schema 要求必须有 email 字段，但你的数据里没有。听起来简单，但"明明写了却还报缺失"的情况很常见。

为什么"写了还报缺失"

1. 字段名拼错 / 大小写不一致

Schema 要的是 email，你数据里是 Email 或 e-mail——JSON 字段名区分大小写，差一个字符就算缺失。从 Excel 或别的语言反序列化来的数据最容易踩这个坑（如 Go 的 json:"eMail" tag、Python 的 snake_case）。肉眼比对两份长字段列表效率很低，用 JSON Diff 把"实际数据"和"一份已知合法的样例"对比，差异字段立刻现形。

2. 嵌套层级搞错

required 是针对它所在的那一层对象生效的。比如：

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "required": ["email"],
      "properties": { "email": { "type": "string" } }
    }
  }
}

这里的 required: ["email"] 只约束 user 这个子对象，不约束顶层。如果你的 email 放在顶层，就会报缺失。报错信息里的路径（如 user.email）就是按层级给的——先看路径再改数据，别急着全文件搜字段名。

3. 数组元素忘了包一层

数组里每个元素都要满足 items 里的 Schema。常见错误是给数组本身写 required，而不是给 items 里的对象写：

{
  "type": "array",
  "items": {
    "type": "object",
    "required": ["id"]
  }
}

报错路径会带数组下标（如 users.2.id），表示第三个元素缺 id——比"数组校验失败"这种粗粒度报错好用得多。

additionalProperties 的坑

如果你设了 "additionalProperties": false，那么任何 Schema 没声明的字段都会报错（不只是缺字段，多字段也错）。调试阶段建议先设成 true 或注释掉，定位完再收紧。

还有一个高频混淆点：required 写在 properties 里面是无效的——它必须作为对象的兄弟关键字与 properties 平级。Schema 校验器一般不报这个写法错误，它只是静默不生效，让人误以为"必填没起作用"。

怎么用工具逐步定位

打开 ToolVault 工具匣 的 JSON Schema 校验工具：

1. 左边贴 JSON 数据，右边贴 Schema；
2. 点校验，工具会逐条列出所有错误（不止第一个），并标出出错的字段路径，如 user.email；
3. 对照路径，检查是拼错、层级错还是类型错；
4. 先用 JSON 格式化工具 把数据和 Schema 都格式化，层级一眼看清，避免看错嵌套；
5. 修完后如果 Schema 本身也要跟着改，用 JSON Schema 编辑器 调整结构，或用 JSON Schema 生成器 从样例数据反向生成骨架。

FAQ

多个 required 缺失，为什么只报一个？

严格的校验器可能遇到第一个就停；本站工具会列出全部错误，方便一次性改完。

type 不对也会报 required 吗？

不会。类型错误是 type 关键字报的（should be string），和 required 是两条独立的错误。看 keyword 字段就能区分。

能不能让某些字段"二选一必填"？

可以，用 oneOf 或 anyOf 包两组 required，比单纯 required 更灵活。例如"手机号和邮箱至少填一个"：

{
  "anyOf": [
    { "required": ["phone"] },
    { "required": ["email"] }
  ]
}

字段存在但值是 null，为什么还算"通过"？

required 只检查字段是否存在，不检查值。"email": null 能通过 required，但过不了 type: "string"。要同时禁止 null，把类型写成 "type": ["string"] 并配合 nullable: false（OpenAPI）或在 Schema 里显式 not: { "type": "null" }。

本文由 ToolVault 工具匣 提供。相关工具：JSON Schema 校验、JSON 格式化、JSON Diff。访问 首页 查看更多开发者工具。