用验证报告代替布尔结果定位 JSON Schema 中缺失或类型错误的字段

用 JSON_SCHEMA_VALID() 做判断时，结果只有 1 或 0，它适合做门禁，却不适合直接回答“到底是哪一个字段不符合规则”。更适合排查和记录的写法是调用 JSON_SCHEMA_VALIDATION_REPORT()：成功时得到 {"valid": true}，失败时还能读取原因、文档位置、Schema 位置和失败关键字。

官方文档：https://dev.mysql.com/doc/refman/8.4/en/json-validation-functions.html

下面用一份带有必填字段和类型约束的对象 Schema 做说明。文章只讨论报告结构和错误定位，不展开 JSON_TABLE 的数据展开。

先用同一份 Schema 固定校验边界

先把“哪些字段必须存在”和“字段应该是什么类型”写进 Schema。示例中 user_id 必须是整数，profile 必须包含 email 与 age，status 只能取两个枚举值。

-- 这份 Schema 同时演示 required、type 和 enum 三类约束
SET @schema = '{
  "type": "object",
  "properties": {
    "user_id": {"type": "integer"},
    "profile": {
      "type": "object",
      "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"}
      },
      "required": ["email", "age"]
    },
    "status": {"type": "string", "enum": ["active", "paused"]}
  },
  "required": ["user_id", "profile", "status"]
}';

这里要先分清两个边界：Schema 或文档不是合法 JSON 时，函数会报输入错误；JSON 合法但不符合 Schema 时，才进入校验失败报告。这样排查时不会把“输入无法解析”和“字段规则不满足”混成同一种问题。

把布尔校验改成验证报告

同一份文档，使用布尔函数只能得到失败标记。改成报告函数后，可以把返回值作为 JSON 继续保存、提取或交给服务层。

-- age 故意传成字符串，用于观察 type 约束对应的报告
SET @document = '{
  "user_id": 101,
  "profile": {"email": "dev@example.com", "age": "36"},
  "status": "active"
}';

-- 报告函数返回 JSON 文档，而不是只返回 0 或 1
SET @report = JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);

-- JSON_PRETTY 只负责提高阅读性，不改变报告字段
SELECT JSON_PRETTY(@report) AS validation_report;

失败报告通常包含五类信息：valid 表示是否通过，reason 给出可读原因，schema-location 指向 Schema 中的约束位置，document-location 指向输入文档中的位置，schema-failed-keyword 表示触发失败的关键字。

按报告字段定位问题

报告字段名中有连字符，使用 JSON_EXTRACT() 读取时，要把成员名写成 $."document-location" 这样的带引号路径。不要把它当成普通的 MySQL JSON Path 下标，也不要把报告里的 #/profile/age 误读成 $.profile.age。

-- 把报告拆成应用层容易消费的五个字段
SELECT
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.valid')) AS is_valid,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.reason')) AS failure_reason,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$."document-location"')) AS document_location,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$."schema-location"')) AS schema_location,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$."schema-failed-keyword"')) AS failed_keyword;

定位时先看 failed_keyword，再看两个位置：schema-location 告诉你哪条约束触发了，document-location 告诉你输入文档的哪一段需要修正。reason 适合直接放进日志或错误响应，但程序分支最好依赖结构化字段，不要解析自然语言句子。

用两份最小输入区分缺失字段与类型错误

同一个 Schema 下，输入问题不同，报告的关注点也不同。先看类型错误：age 存在，但值是字符串，schema-failed-keyword 会落在 type，文档位置会指向 profile.age 对应的 JSON Pointer。

-- age 存在但类型不对：排查重点是 type 和具体文档位置
SET @document = '{
  "user_id": 101,
  "profile": {"email": "dev@example.com", "age": "36"},
  "status": "active"
}';
SELECT JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document));

再看缺失字段：删除 profile.age，报告会反映 required 约束没有满足。这里不要预设所有实现都会把路径精确到缺失键本身；缺失属性不存在于文档中，报告可能定位到它所在的对象或 Schema 位置，真正有用的是同时阅读 reason、schema-location 和 document-location。

-- age 不存在：排查重点是 required 和所在对象路径
SET @document = '{
  "user_id": 101,
  "profile": {"email": "dev@example.com"},
  "status": "active"
}';
SELECT JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document));

报告里的位置是 JSON Pointer URI 片段：# 代表整个文档，#/profile 代表顶层 profile 属性。它和 MySQL 的 JSON Path 语法不是同一套表示法，转换时要在边界处明确标注，避免把斜杠路径直接拼接进 JSON_EXTRACT()。

把报告接入数据流转

在实际系统里，可以把原始文档、Schema 版本、结构化报告和接收时间放进审计记录，也可以只把几个字段返回给 API。关键是不要在得到 0 后立刻丢掉报告，因为后续重试、人工修复和数据质量统计都需要失败原因。

-- 审计表只保存校验上下文，便于后续按失败关键字统计
CREATE TABLE json_validation_audit (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  schema_version VARCHAR(32) NOT NULL,
  document JSON NOT NULL,
  validation_report JSON NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

-- 以当前文档重新生成报告，保证原文与报告属于同一次校验
SET @report = JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);

-- 失败报告与原文一起保存，避免只留下无法定位的布尔值
INSERT INTO json_validation_audit
  (schema_version, document, validation_report)
VALUES
  ('user-v1', CAST(@document AS JSON), @report);

如果业务表使用 CHECK 约束，还可以让数据库负责拒绝不合规数据，并在插入失败后读取报告或警告信息定位问题。应用层校验适合给出更早的反馈，数据库约束适合守住最终写入边界，两者可以根据数据责任边界组合使用。

常见问题

报告返回 valid 为 true 时还有其它字段吗？

成功时重点是 valid 为 true；失败时才需要关注原因、Schema 位置、文档位置和失败关键字。调用方应按字段是否存在处理，而不是假设成功和失败报告拥有完全相同的结构。

为什么 document-location 看起来不像 $.profile.age？

因为报告使用 JSON Pointer URI 片段表示位置，常见形式是 #/profile/age。MySQL 的 JSON 函数路径通常使用 $.profile.age，两者要在程序中显式转换，不能直接混用。

能不能用 reason 做程序分支？

不建议。reason 面向人阅读，程序分支应优先使用 schema-failed-keyword 和结构化路径；需要展示时再把 reason 作为提示文本。

总结

JSON_SCHEMA_VALID() 适合快速判断，JSON_SCHEMA_VALIDATION_REPORT() 适合排错和数据流转。实际使用时记住三点：先固定 Schema 边界，再保留完整报告，最后用 schema-failed-keyword、schema-location 和 document-location 做定位。这样缺失字段、类型错误和枚举不匹配就不会再被一个孤立的 0 淹没。