JSON 语法正确却导入失败？用 JSON Schema 检查字段和类型

接口能返回 JSON，并不意味着每条记录都符合导入要求。商品编号缺失、库存是字符串、字段名写错，都可能在后续操作才暴露问题。

用 JSON 格式化与校验 先检查语法，再用 JSON Schema 校验器 检查约束，可以更早发现这类错误。本教程的商品数据是练习样例，不包含真实订单或客户资料。

准备一份可以通过的商品记录

把下面内容复制到校验器的“输入”区域：

{
  "sku": "SKU-001",
  "name": "桌面收纳盒",
  "stock": 12
}

这个对象的要求是：sku 与 name 为非空字符串，stock 是大于等于 0 的整数，而且不接受未知字段。先写明这些要求，再写 Schema，避免把偶然出现的样例当作完整业务规则。

第一步：把规则放入 Schema 区域

在“JSON Schema”区域粘贴下列规则，点击输入区下方的操作按钮执行校验：

{
  "type": "object",
  "required": ["sku", "name", "stock"],
  "properties": {
    "sku": { "type": "string", "minLength": 1 },
    "name": { "type": "string", "minLength": 1 },
    "stock": { "type": "integer", "minimum": 0 }
  },
  "additionalProperties": false
}

结果应显示校验通过。这里没有写入实际数据库，也没有把 stock 自动转换成其他类型；只是判断输入是否符合这份规则。

properties 描述字段约束，required 声明必填项，additionalProperties: false 拒绝未声明字段。仅把字段写进 properties，并不代表它必填。规则含义可对照 JSON Schema 官方对象说明。

第二步：一次只改一个字段，观察失败位置

每次从原样例重新开始，按下表修改后再执行一次校验：

修改	应出现的判断	修正方法
删除 sku	缺少必填字段	补回编号
将 stock 改成 "12"	stock 应为整数	按接口约定使用数字 12
将 stock 改成 -1	小于允许的最小值	确认业务是否允许负库存
新增 stok: 12	出现额外字段	检查是否把 stock 拼错

错误信息可能包含 /stock 这样的路径。先看路径定位数据，再看整数、最小值或必填提示；不要只删除报错字段，因为那可能让另一条必填规则失败。

第三步：理解空值、空字符串和缺失

"name": "" 是空字符串，"name": null 是空值，没有 name 则是字段缺失。它们是三种不同情况。本例分别由 minLength、type 和 required 处理。

字符串中只放空格仍可能通过 minLength: 1。如果业务要求“不能全是空白”，需要进一步制定规则或在业务程序中清理空白，不能把“校验通过”理解成每个值都适合保存。

第四步：批量记录要用数组规则

需要检查多条商品时，输入应为数组，Schema 顶层也要改成 array，把原来的对象规则放入 items：

{
  "type": "array",
  "items": {
    "type": "object",
    "required": ["sku", "stock"],
    "properties": {
      "sku": { "type": "string", "minLength": 1 },
      "stock": { "type": "integer", "minimum": 0 }
    }
  }
}

这是一份简化的批量规则：它没有要求 name，也没有禁止额外字段。不要把简化样例直接替换正式接口规范。批量数据里的 /1/stock 指向第二条记录的库存；数组下标从 0 开始。

常见误区：校验不会替你清洗数据

工具不会替你补默认值、查询 SKU 是否存在或检查数据库里的重复记录。长编号应按接口约定使用字符串；把大整数写成 JSON 数字，可能在解析时就失去精度。

当前实现使用 JSON Schema 2020-12 校验器。练习先使用本文这些基本关键字；不要假定外部 Schema 链接会自动下载，也不要把没有配置的自定义格式视为已验证。

改完后再比一次差异

用 JSON 差异比较 对照修改前后数据，确认只改动了预期字段，再回到 Schema 页重跑。若输入本身无法解析，先参考 JSON 格式化、校验与键排序指南。