MySQL JSON_SCHEMA_VALIDATION_REPORT() 函数使用指南

MySQL JSON_SCHEMA_VALIDATION_REPORT() 函数根据指定的 JSON 模式验证一个 JSON 文档，并返回一个验证报告。

JSON_SCHEMA_VALIDATION_REPORT() 语法

这里是 MySQL JSON_SCHEMA_VALIDATION_REPORT() 的语法：

JSON_SCHEMA_VALIDATION_REPORT(schema, json_doc)

参数

schema

必需的。一个 JSON 模式。它必须是一个有效的 JSON 对象。

json_doc

必需的。被验证的 JSON 文档。

返回值

JSON_SCHEMA_VALIDATION_REPORT() 函数返回一个关于验证结果的报告，它是一个 JSON 对象。这个报告中包含如下成员：

• valid: true 表示 JSON 文档通过了验证， false 表示 JSON 文档没有通过验证。
• reason: 验证失败的原因。
• schema-location: 一个 JSON 指针 URI 片段标识符，指示验证在 JSON shcema 中的位置
• document-location: 一个 JSON 指针 URI 片段标识符，指示验证在 JSON 文档中失败的位置
• schema-failed-keyword: 一个字符串，包含违反的 JSON shcema 中关键字或属性的名称

如果 JSON 文档通过验证，报告中只有 valid: true 这个一个成员。其他的成员只有验证失败时才会出现在报告中。

如果任何一个参数为 NULL，此函数将返回 NULL。

如果 schema 不是 JSON 对象或者 json_doc 不是有效的 JSON 文档，MySQL 会给出一个错误提示。

JSON_SCHEMA_VALIDATION_REPORT() 示例

本示例展示了如何使用 JSON_SCHEMA_VALIDATION_REPORT() 函数验证一个 JSON 文档是否符合一个 JSON 模式。

首先，让我们创建一个 JSON 模式：

SET @schema = '{
      "id": "http://json-schema.org/geo",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "x": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "y": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      }
    }';

这里，我们创建了 JSON 模式，其中：

• "type": "object" 表示 JSON 文档必须是一个 JSON 对象。

• "properties" 中定义了对象中的成员列表，以及每个成员的约束。这里的定义了两个成员：

  • x - 数字类型，最大值是 90，最小值是 -90。
  • y - 数字类型，最大值是 180，最小值是 -180。

• "required": ["x", "y"] 定义了对象中必须有成员 x 和 y。

接着，让我们创建一个 JSON 文档：

SET @json_doc = '{"x": 1, "y": 2}';

然后，让我们验证 JSON 文档是否和 JSON 模式匹配：

SELECT JSON_SCHEMA_VALIDATION_REPORT(@schema, @json_doc) AS Report\G

*************************** 1. row ***************************
Report: {"valid": true}

这里，返回了 {"valid": true} 说明了 JSON 文档和 JSON schema 是匹配的。

如果我们改一下 JSON 文档，将 y 的值修改为 200:

SET @json_doc = '{"x": 1, "y": 200}';

让我们再次验证 JSON 文档是否和 JSON 模式匹配：

SELECT JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @json_doc)) AS Report\G

*************************** 1. row ***************************
Report: {
  "valid": false,
  "reason": "The JSON document location '#/y' failed requirement 'maximum' at JSON Schema location '#/properties/y'",
  "schema-location": "#/properties/y",
  "document-location": "#/y",
  "schema-failed-keyword": "maximum"
}

因为在 JSON schema 中限定了 y 的范围是 -180 到 180，而现在 y 的值为 200，所以验证失败了。

注意：为了更易于阅读，这里对报告使用了 JSON_PRETTY() 函数进行了美化。