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"] 定义了对象中必须有成员 xy

接着,让我们创建一个 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 的范围是 -180180,而现在 y 的值为 200,所以验证失败了。

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