# 12.18.7 JSON 模式验证函数

从 MySQL 8.0.17 开始,MySQL 支持针对符合以下标准的 JSON 模式验证 JSON 文档JSON Schema 规范草案 4 (opens new window).这可以使用本节中详述的任何一个函数来完成,这两个函数都有两个参数,一个 JSON 模式和一个根据模式验证的 JSON 文档。JSON_SCHEMA_VALID()如果文档对模式进行验证,则返回 true,否则返回 false;JSON_SCHEMA_VALIDATION_REPORT()提供 JSON 格式的验证报告。

这两个函数都处理空或无效输入,如下所示:

  • 如果至少有一个论点是空值, 函数返回空值.

  • 如果至少有一个参数不是有效的 JSON,则函数会引发错误 (ER_INVALID_TYPE_FOR_JSON (opens new window))

  • 此外,如果架构不是有效的 JSON 对象,则函数返回ER_INVALID_JSON_TYPE (opens new window).

    MySQL 支持必需的JSON 模式中的属性以强制包含必需的属性(请参阅函数描述中的示例)。

    MySQL 支持id,$模式,描述, 和类型JSON 模式中的属性,但不需要任何这些。

    MySQL 不支持 JSON 模式中的外部资源;使用$参考关键词原因JSON_SCHEMA_VALID()失败ER_NOT_SUPPORTED_YET (opens new window).

笔记

MySQL 支持 JSON 模式中的正则表达式模式,它支持但默默地忽略无效模式(参见描述JSON_SCHEMA_VALID()例如)。

以下列表中详细描述了这些功能:

  • JSON_SCHEMA_VALID(*图式*,*文档*)

    验证 JSON*文档针对 JSON图式.两个都图式文档*是必要的。架构必须是有效的 JSON 对象;该文档必须是有效的 JSON 文档。前提是满足这些条件: 如果文档根据模式验证,则函数返回 true (1);否则,它返回 false (0)。

    在这个例子中,我们设置了一个用户变量@schema到地理坐标的 JSON 模式的值,以及另一个@文档到包含一个这样的坐标的 JSON 文档的值。然后我们验证@文档根据验证@schema通过使用它们作为参数JSON_SCHEMA_VALID()

    mysql> SET @schema = '{
        '>  "id": "http://json-schema.org/geo",
        '> "$schema": "http://json-schema.org/draft-04/schema#",
        '> "description": "A geographical coordinate",
        '> "type": "object",
        '> "properties": {
        '>   "latitude": {
        '>     "type": "number",
        '>     "minimum": -90,
        '>     "maximum": 90
        '>   },
        '>   "longitude": {
        '>     "type": "number",
        '>     "minimum": -180,
        '>     "maximum": 180
        '>   }
        '> },
        '> "required": ["latitude", "longitude"]
        '>}';
    Query OK, 0 rows affected (0.01 sec)
    
    mysql> SET @document = '{
        '> "latitude": 63.444697,
        '> "longitude": 10.445118
        '>}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_SCHEMA_VALID(@schema, @document);
    +---------------------------------------+
    | JSON_SCHEMA_VALID(@schema, @document) |
    +---------------------------------------+
    |                                     1 |
    +---------------------------------------+
    1 row in set (0.00 sec)
    

    自从@schema包含必需的属性,我们可以设置@文档到一个在其他方面有效但不包含所需属性的值,然后对其进行测试@schema, 像这样:

    mysql> SET @document = '{}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_SCHEMA_VALID(@schema, @document);
    +---------------------------------------+
    | JSON_SCHEMA_VALID(@schema, @document) |
    +---------------------------------------+
    |                                     0 |
    +---------------------------------------+
    1 row in set (0.00 sec)
    

    如果我们现在设置@schema到相同的 JSON 模式,但没有必需的属性,@文档验证,因为它是一个有效的 JSON 对象,即使它不包含任何属性,如下所示:

    mysql> SET @schema = '{
        '> "id": "http://json-schema.org/geo",
        '> "$schema": "http://json-schema.org/draft-04/schema#",
        '> "description": "A geographical coordinate",
        '> "type": "object",
        '> "properties": {
        '>   "latitude": {
        '>     "type": "number",
        '>     "minimum": -90,
        '>     "maximum": 90
        '>   },
        '>   "longitude": {
        '>     "type": "number",
        '>     "minimum": -180,
        '>     "maximum": 180
        '>   }
        '> }
        '>}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_SCHEMA_VALID(@schema, @document);
    +---------------------------------------+
    | JSON_SCHEMA_VALID(@schema, @document) |
    +---------------------------------------+
    |                                     1 |
    +---------------------------------------+
    1 row in set (0.00 sec)
    

    JSON_架构_VALID() 和 CHECK 约束。 JSON_SCHEMA_VALID()也可以用来强制查看约束。

    考虑表格地理如此处所示创建,带有一个 JSON 列协调表示地图上的经纬度点,由用作参数的 JSON 模式控制JSON_SCHEMA_VALID()作为表达式传递的调用查看对该表的约束:

    mysql> CREATE TABLE geo (
        ->     coordinate JSON,
        ->     CHECK(
        ->         JSON_SCHEMA_VALID(
        ->             '{
        '>                 "type":"object",
        '>                 "properties":{
        '>                       "latitude":{"type":"number", "minimum":-90, "maximum":90},
        '>                       "longitude":{"type":"number", "minimum":-180, "maximum":180}
        '>                 },
        '>                 "required": ["latitude", "longitude"]
        '>             }',
        ->             coordinate
        ->         )
        ->     )
        -> );
    Query OK, 0 rows affected (0.45 sec)
    

    笔记

    因为一个 MySQL查看约束不能包含对变量的引用,您必须将 JSON 模式传递给JSON_SCHEMA_VALID()使用它为表指定这样的约束时是内联的。

    我们将表示坐标的 JSON 值分配给三个变量,如下所示:

    mysql> SET @point1 = '{"latitude":59, "longitude":18}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SET @point2 = '{"latitude":91, "longitude":0}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SET @point3 = '{"longitude":120}';
    Query OK, 0 rows affected (0.00 sec)
    

    这些值中的第一个是有效的,如下所示插入陈述:

    mysql> INSERT INTO geo VALUES(@point1);
    Query OK, 1 row affected (0.05 sec)
    

    第二个 JSON 值无效,因此约束失败,如下所示:

    mysql> INSERT INTO geo VALUES(@point2);
    ERROR 3819 (HY000): Check constraint 'geo_chk_1' is violated.
    

    在 MySQL 8.0.19 及更高版本中,您可以获得有关故障性质的精确信息——在这种情况下,纬度值超过了模式中定义的最大值——通过发出显示警告陈述:

    mysql> SHOW WARNINGS\G
    *************************** 1. row ***************************
      Level: Error
       Code: 3934
    Message: The JSON document location '#/latitude' failed requirement 'maximum' at
    JSON Schema location '#/properties/latitude'.
    *************************** 2. row ***************************
      Level: Error
       Code: 3819
    Message: Check constraint 'geo_chk_1' is violated.
    2 rows in set (0.00 sec)
    

    上面定义的第三个坐标值也是无效的,因为它缺少所需的纬度财产。和以前一样,您可以通过尝试将值插入地理表,然后发出显示警告然后:

    mysql> INSERT INTO geo VALUES(@point3);
    ERROR 3819 (HY000): Check constraint 'geo_chk_1' is violated.
    mysql> SHOW WARNINGS\G
    *************************** 1. row ***************************
      Level: Error
       Code: 3934
    Message: The JSON document location '#' failed requirement 'required' at JSON
    Schema location '#'.
    *************************** 2. row ***************************
      Level: Error
       Code: 3819
    Message: Check constraint 'geo_chk_1' is violated.
    2 rows in set (0.00 sec)
    

    第 13.1.20.6 节,“检查约束”, 了解更多信息。

    JSON Schema 支持为字符串指定正则表达式模式,但 MySQL 使用的实现会默默地忽略无效模式。这意味着JSON_SCHEMA_VALID()即使正则表达式模式无效,也可以返回 true,如下所示:

    mysql> SELECT JSON_SCHEMA_VALID('{"type":"string","pattern":"("}', '"abc"');
    +---------------------------------------------------------------+
    | JSON_SCHEMA_VALID('{"type":"string","pattern":"("}', '"abc"') |
    +---------------------------------------------------------------+
    |                                                             1 |
    +---------------------------------------------------------------+
    1 row in set (0.04 sec)
    
  • JSON_SCHEMA_VALIDATION_REPORT(*图式*,*文档*)

    验证 JSON*文档针对 JSON图式.两个都图式文档*是必要的。与 JSON 一样_有效的_SCHEMA(),架构必须是有效的 JSON 对象,文档必须是有效的 JSON 文档。如果满足这些条件,该函数会以 JSON 文档的形式返回关于验证结果的报告。如果 JSON 文档根据 JSON Schema 被认为是有效的,则该函数返回一个具有一个属性的 JSON 对象有效的具有“真”值。如果 JSON 文档验证失败,该函数将返回一个 JSON 对象,其中包括此处列出的属性:

    • 有效的:对于失败的架构验证,始终为“假”

    • 原因:包含失败原因的人类可读字符串

    • 模式位置:一个 JSON 指针 URI 片段标识符,指示在 JSON 模式中验证失败的位置(请参阅此列表后面的注释)

    • 文件位置:一个 JSON 指针 URI 片段标识符,指示在 JSON 文档中验证失败的位置(请参阅此列表后面的注释)

    • 架构失败的关键字: 一个字符串,包含违反的 JSON 模式中的关键字或属性的名称

    笔记

    JSON 指针 URI 片段标识符定义在RFC 6901 - JavaScript 对象表示法 (JSON) 指针 (opens new window).(这些是不是与使用的 JSON 路径表示法相同JSON_EXTRACT()和其他 MySQL JSON 函数。)在这种表示法中,#代表整个文档,并且#/myprop表示包含在名为的顶级属性中的文档部分我的道具.有关详细信息,请参阅刚刚引用的规范和本节后面显示的示例。

    在这个例子中,我们设置了一个用户变量@schema到地理坐标的 JSON 模式的值,以及另一个@文档到包含一个这样的坐标的 JSON 文档的值。然后我们验证@文档根据验证@schema通过使用它们作为参数JSON_SCHEMA_VALIDATION_REORT()

    mysql> SET @schema = '{
        '>  "id": "http://json-schema.org/geo",
        '> "$schema": "http://json-schema.org/draft-04/schema#",
        '> "description": "A geographical coordinate",
        '> "type": "object",
        '> "properties": {
        '>   "latitude": {
        '>     "type": "number",
        '>     "minimum": -90,
        '>     "maximum": 90
        '>   },
        '>   "longitude": {
        '>     "type": "number",
        '>     "minimum": -180,
        '>     "maximum": 180
        '>   }
        '> },
        '> "required": ["latitude", "longitude"]
        '>}';
    Query OK, 0 rows affected (0.01 sec)
    
    mysql> SET @document = '{
        '> "latitude": 63.444697,
        '> "longitude": 10.445118
        '>}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);
    +---------------------------------------------------+
    | JSON_SCHEMA_VALIDATION_REPORT(@schema, @document) |
    +---------------------------------------------------+
    | {"valid": true}                                   |
    +---------------------------------------------------+
    1 row in set (0.00 sec)
    

    现在我们设置@文档这样它就为其属性之一指定了非法值,如下所示:

    mysql> SET @document = '{
        '> "latitude": 63.444697,
        '> "longitude": 310.445118
        '> }';
    

    验证@文档现在在测试时失败JSON_SCHEMA_VALIDATION_REPORT().函数调用的输出包含有关失败的详细信息(函数由JSON_PRETTY()提供更好的格式),如下所示:

    mysql> SELECT JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document))\G
    *************************** 1. row ***************************
    JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document)): {
      "valid": false,
      "reason": "The JSON document location '#/longitude' failed requirement 'maximum' at JSON Schema location '#/properties/longitude'",
      "schema-location": "#/properties/longitude",
      "document-location": "#/longitude",
      "schema-failed-keyword": "maximum"
    }
    1 row in set (0.00 sec)
    

    自从@schema包含必需的属性,我们可以设置@文档到一个在其他方面有效但不包含所需属性的值,然后对其进行测试@schema.的输出JSON_SCHEMA_VALIDATION_REPORT()表明由于缺少必需的元素而导致验证失败,如下所示:

    mysql> SET @document = '{}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document))\G
    *************************** 1. row ***************************
    JSON_PRETTY(JSON_SCHEMA_VALIDATION_REPORT(@schema, @document)): {
      "valid": false,
      "reason": "The JSON document location '#' failed requirement 'required' at JSON Schema location '#'",
      "schema-location": "#",
      "document-location": "#",
      "schema-failed-keyword": "required"
    }
    1 row in set (0.00 sec)
    

    如果我们现在设置@schema到相同的 JSON 模式,但没有必需的属性,@文档验证,因为它是一个有效的 JSON 对象,即使它不包含任何属性,如下所示:

    mysql> SET @schema = '{
        '> "id": "http://json-schema.org/geo",
        '> "$schema": "http://json-schema.org/draft-04/schema#",
        '> "description": "A geographical coordinate",
        '> "type": "object",
        '> "properties": {
        '>   "latitude": {
        '>     "type": "number",
        '>     "minimum": -90,
        '>     "maximum": 90
        '>   },
        '>   "longitude": {
        '>     "type": "number",
        '>     "minimum": -180,
        '>     "maximum": 180
        '>   }
        '> }
        '>}';
    Query OK, 0 rows affected (0.00 sec)
    
    mysql> SELECT JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);
    +---------------------------------------------------+
    | JSON_SCHEMA_VALIDATION_REPORT(@schema, @document) |
    +---------------------------------------------------+
    | {"valid": true}                                   |
    +---------------------------------------------------+
    1 row in set (0.00 sec)