MySQL :: X DevAPI 用户指南 :: 4.6 JSON 模式验证

4.6 JSON 模式验证

可以将集合配置为根据 JSON 模式验证文档。这使您能够要求文档在插入或更新到集合中之前具有特定的结构。您可以按照 https://json-schema.fullstack.org.cn 中的描述指定 JSON 模式。模式验证由服务器执行，如果集合中的文档未通过分配的 JSON 模式的验证，则服务器会返回错误消息。有关 MySQL 中 JSON 模式验证的更多信息，请参见 JSON 模式验证函数。本节介绍如何将集合配置为根据 JSON 模式验证文档。

注意

Connector/J 实现 JSON 模式验证的方式与本节中描述的模型非常不同。有关详细信息，请参见模式验证（位于 MySQL Connector/J 开发者指南中）。

要启用或修改 JSON 模式验证，您可以向集合提供如下所示的 validation JSON 对象

{
    validation: {
      level: "off|strict",
      schema: "json-schema"
    }
}

其中，validation 是一个 JSON 对象，其中包含可用于配置 JSON 模式验证的键。第一个键是 level，它可以取值 strict 或 off。第二个键 schema 是一个 JSON 模式，如 https://json-schema.fullstack.org.cn 中所定义。如果 level 键设置为 strict，则在将文档添加到集合中时，或者如果文档已在集合中，则在通过某些操作更新文档时，将根据 json-schema 对文档进行验证。如果文档未通过验证，则服务器会生成错误并且操作失败。如果 level 键设置为 off，则不会根据 json-schema 验证文档。

创建已验证的集合

要在创建新集合时启用 JSON 模式验证，请提供如上所述的 validation JSON 对象。例如，要创建一个包含经度和纬度值的集合，并要求将这些值验证为数字

MySQL Shell JavaScript 代码

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "https://json-schema.fullstack.org.cn/geo",
      "$schema": "https://json-schema.fullstack.org.cn/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

MySQL Shell Python 代码

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "https://json-schema.fullstack.org.cn/geo",
        "$schema": "https://json-schema.fullstack.org.cn/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

Node.js JavaScript 代码

var coll = schema.createCollection("longlang", {
  validation: {
    level: "strict",
    schema:   {
      "id": "https://json-schema.fullstack.org.cn/geo",
      "$schema": "https://json-schema.fullstack.org.cn/draft-06/schema#",
      "description": "A geographical coordinate",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": ["latitude", "longitude"]
    }
  }
})

C# 代码

var collOptions = CreateCollectionOptions() {
  reuseExistingObject = false,
  validation = Validation() {
    level = ValidationLevel.Strict,
    schema = "{\"id\": \"https://json-schema.fullstack.org.cn/geo\","
             + "\"$schema\": \"https://json-schema.fullstack.org.cn/draft-06/schema#\","
             + "       \"description\": \"A geographical coordinate\","
             + "       \"type\": \"object\","
             + "       \"properties\": {"
             + "          \"latitude\": {"
             + "             \"type\": \"number\""
             + "          },"
             + "          \"longitude\": {"
             + "             \"type\": \"number\""
             + "          }"
             + "       },"
             + "       \"required\": [\"latitude\", \"longitude\"]"
             + "  }"
    }
};

var coll = schema.CreateCollection("longlang", collOptions);

Python 代码

coll = schema.create_collection("longlang", validation={
    "level": "strict",
    "schema":   {
        "id": "https://json-schema.fullstack.org.cn/geo",
        "$schema": "https://json-schema.fullstack.org.cn/draft-06/schema#",
        "description": "A geographical coordinate",
        "type": "object",
        "properties": {
            "latitude": {
                "type": "number"
            },
            "longitude": {
                "type": "number"
            }
        },
        "required": ["latitude", "longitude"]
    }
})

修改集合验证

您可以修改集合以控制文档的 JSON 模式验证。例如，您可以启用或禁用验证，或者更改用于验证文档的 JSON 模式。

要修改集合的 JSON 模式验证，请在调用 Collection.modify() 方法时提供 validation JSON 对象。例如，要修改集合以禁用 JSON 模式验证，validation 对象将是

{ 
   validation: {
       "level": "off"
   }
}

修改 JSON 模式验证时，您可以单独提供 level 选项以仅更改模式验证的级别。例如，传递上面显示的 JSON 对象以禁用 JSON 模式验证。这不会更改之前指定的 JSON 模式，也不会从集合中删除 JSON 模式。或者，您可以通过仅传递新的 JSON 模式对象来仅修改模式。