JSON_SCHEMA_VALIDATION_REPORT

描述

该函数用于返回一个详细的验证报告。

语法

JSON_SCHEMA_VALIDATION_REPORT(schema, document)

说明

• 参数 schema 用于指定 JSON Schema，且 Schema 必须是有效的 JSON 对象。

  • JSON Schema 中支持使用 required 属性来强制必须包含的属性。

  • JSON Schema 中支持 id、 $schema、description 和 type 属性，但不要求必须提供这些属性。

• 参数 document 用于指定待验证的 JSON 文档，该 JSON 文档必须是有效的 JSON 文档。

• 如果其中有一个参数不是有效的 JSON，该函数就会引发错误。

不同于 JSON_SCHEMA_VALID() 函数，JSON_SCHEMA_VALIDATION_REPORT() 函数用于返回一个详细的验证报告，且该报告是一个 JSON 对象。如果 JSON 文档符合 JSON Schema 规范，则该函数将返回一个 valid 属性值为 true 的 JSON 对象；如果 JSON 文档不符合 JSON Schema 规范，则该函数将返回一个非空的 JSON 对象，其中包含了验证失败的详细信息。

验证失败的信息中主要包含以下属性信息：

• valid：验证失败时，该值始终为 false。

• reason：显示验证失败的原因。

• schema-location：指示 JSON Schema 中验证失败的位置。

• document-location：指示 JSON 文档中验证失败的位置。

• schema-failed-keyword：显示 JSON Schema 中违反规范的关键字或属性名称。

示例

• 如下示例中，通过 '{"type": "string"}' 定义了一个 JSON Schema，且该 Schema 指明了有效的 JSON 数据应该是一个字符串类型。'"JSON_doc"' 是一个有效的 JSON 字符串，符合 Schema 所规定的字符串类型。

  SELECT JSON_SCHEMA_VALIDATION_REPORT('{"type": "string"}', '"JSON_doc"');

  返回结果如下：

  +-------------------------------------------------------------------+
  | JSON_SCHEMA_VALIDATION_REPORT('{"type": "string"}', '"JSON_doc"') |
  +-------------------------------------------------------------------+
  | {"valid": true}                                                   |
  +-------------------------------------------------------------------+
  1 row in set (0.001 sec)

• 如下示例中，定义了一个 JSON Schema，要求其 age 属性必须是一个大于等于 18 的整数。

  SET @schema = '{"type": "object", "properties": {"age": {"type": "integer", "minimum": 18}}, "required": ["age"]}';

  定义一个 JSON 文档，其 age 值为 17，不符合 JSON Schema 规范。

  SET @document = '{"age": 17}';

  使用 JSON_SCHEMA_VALIDATION_REPORT() 函数获取验证报告。

  SELECT JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);

  返回结果如下：

  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  | JSON_SCHEMA_VALIDATION_REPORT(@schema, @document)                                                                                                                                                                                                |
  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  | {"valid": false, "reason": "The JSON document location '#/age' failed requirement 'minimum' at JSON Schema location '#/properties/age", "schema-location": "#/properties/age", "document-location": "#/age", "schema-failed-keyword": "minimum"} |
  +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  1 row in set (0.001 sec)