Docs 菜单
Docs 主页
/
MongoDB Manual
/ / / /

$jsonSchema

在此页面上

  • 定义
  • 行为
  • 示例
  • JSON schema
$jsonSchema

$jsonSchema操作符匹配满足指定JSON schema 的文档。

$jsonSchema操作符表达式的语法如下:

{ $jsonSchema: <JSON Schema object> }

其中JSON schema对象的格式符合 4JSON schema 标准 的 草案

{ <keyword1>: <value1>, ... }

例如:

{
$jsonSchema: {
required: [ "name", "major", "gpa", "address" ],
properties: {
name: {
bsonType: "string",
description: "must be a string and is required"
},
address: {
bsonType: "object",
required: [ "zipcode" ],
properties: {
"street": { bsonType: "string" },
"zipcode": { bsonType: "string" }
}
}
}
}
}

有关MongoDB支持的关键字列表,请参阅可用关键字。

注意

MongoDB 支持4 JSON schema 的 草案,包括 核心规范 验证规范 ,但存在一些差异。有关详细信息,请参阅扩展省略

有关 JSON schema 的更多信息,请参阅 官方网站

featureCompatibilityVersion必须设立为"3.6"或更高版本才能使用$jsonSchema

您可以在文档验证器中使用$jsonSchema ,对插入和更新操作实施指定的模式:

db.createCollection( <collection>, { validator: { $jsonSchema: <schema> } } )
db.runCommand( { collMod: <collection>, validator:{ $jsonSchema: <schema> } } )

您可以在写入操作的查询条件中使用$jsonSchema来查找集合中满足指定模式的文档:

db.collection.find( { $jsonSchema: <schema> } )
db.collection.aggregate( [ { $match: { $jsonSchema: <schema> } } ] )
db.collection.updateMany( { $jsonSchema: <schema> }, <update> )
db.collection.deleteOne( { $jsonSchema: <schema> } )

要查找集合中 不满足 指定模式的文档,请在 表达式中使用$jsonSchema $nor表达式。示例:

db.collection.find( { $nor: [ { $jsonSchema: <schema> } ] } )
db.collection.aggregate( [ { $match: { $nor: [ { $jsonSchema: <schema> } ] } }, ... ] )
db.collection.updateMany( { $nor: [ { $jsonSchema: <schema> } ] }, <update> )
db.collection.deleteOne( { $nor: [ { $jsonSchema: <schema> } ] } )

以下db.createCollection()方法创建一个名为students的集合,并使用$jsonSchema操作符设置模式验证规则:

db.createCollection("students", {
validator: {
$jsonSchema: {
bsonType: "object",
required: [ "name", "year", "major", "address" ],
properties: {
name: {
bsonType: "string",
description: "must be a string and is required"
},
year: {
bsonType: "int",
minimum: 2017,
maximum: 3017,
description: "must be an integer in [ 2017, 3017 ] and is required"
},
major: {
enum: [ "Math", "English", "Computer Science", "History", null ],
description: "can only be one of the enum values and is required"
},
gpa: {
bsonType: [ "double" ],
description: "must be a double if the field exists"
},
address: {
bsonType: "object",
required: [ "city" ],
properties: {
street: {
bsonType: "string",
description: "must be a string if the field exists"
},
city: {
bsonType: "string",
"description": "must be a string and is required"
}
}
}
}
}
}
} )

给定为集合创建的validator ,以下插入操作将失败,因为当validator需要double时, gpa是整数。

db.students.insertOne( {
name: "Alice",
year: Int32( 2019 ),
major: "History",
gpa: Int32( 3 ),
address: {
city: "NYC",
street: "33rd Street"
}
} )

该操作返回以下错误:

MongoServerError: Document failed validation
Additional information: {
failingDocumentId: ObjectId("61aa577f666a50a8fccd7ec2"),
details: {
operatorName: '$jsonSchema',
schemaRulesNotSatisfied: [
{
operatorName: 'properties',
propertiesNotSatisfied: [
{
propertyName: 'gpa',
description: 'must be a double if the field exists',
details: [ [Object] ]
}
]
}
]
}
}

gpa更改为双精度值后,插入成功:

db.students.insertOne( {
name: "Alice",
year: NumberInt(2019),
major: "History",
gpa: Double(3.0),
address: {
city: "NYC",
street: "33rd Street"
}
} )

您可以在写入操作的查询条件中使用$jsonSchema来查找集合中满足指定模式的文档。

例如,使用以下文档创建样本集合inventory

db.inventory.insertMany( [
{ item: "journal", qty: NumberInt(25), size: { h: 14, w: 21, uom: "cm" }, instock: true },
{ item: "notebook", qty: NumberInt(50), size: { h: 8.5, w: 11, uom: "in" }, instock: true },
{ item: "paper", qty: NumberInt(100), size: { h: 8.5, w: 11, uom: "in" }, instock: 1 },
{ item: "planner", qty: NumberInt(75), size: { h: 22.85, w: 30, uom: "cm" }, instock: 1 },
{ item: "postcard", qty: NumberInt(45), size: { h: 10, w: 15.25, uom: "cm" }, instock: true },
{ item: "apple", qty: NumberInt(45), status: "A", instock: true },
{ item: "pears", qty: NumberInt(50), status: "A", instock: true }
] )

接下来,定义以下示例模式对象:

let myschema = {
required: [ "item", "qty", "instock" ],
properties: {
item: { bsonType: "string" },
qty: { bsonType: "int" },
size: {
bsonType: "object",
required: [ "uom" ],
properties: {
uom: { bsonType: "string" },
h: { bsonType: "double" },
w: { bsonType: "double" }
}
},
instock: { bsonType: "bool" }
}
}

您可以使用$jsonSchema查找集合中满足以下模式的所有文档:

db.inventory.find( { $jsonSchema: myschema } )
db.inventory.aggregate( [ { $match: { $jsonSchema: myschema } } ] )

您可以使用$jsonSchema$nor来查找所有不满足该模式的文档:

db.inventory.find( { $nor: [ { $jsonSchema: myschema } ] } )

或者,您可以更新所有不满足模式的文档:

db.inventory.updateMany( { $nor: [ { $jsonSchema: myschema } ] }, { $set: { isValid: false } } )

或者,您可以删除所有不满足模式的文档:

db.inventory.deleteMany( { $nor: [ { $jsonSchema: myschema } ] } )

MongoDB 支持4 JSON schema 的 草案,包括 核心规范 验证规范 ,但存在一些差异。有关详细信息,请参阅扩展省略

有关 JSON schema 的更多信息,请参阅 官方网站

注意

MongoDB 实施 JSON schema 中的可用关键字的一个子集。有关省略项的完整列表,请参阅省略项

Keyword
类型
定义
行为
bsonType
所有类型
字符串别名或字符串别名数组
接受用于 $type 操作符的相同字符串别名
枚举
所有类型
值数组
枚举字段的所有可能值
类型
所有类型
字符串或唯一字符串的数组

枚举字段可能的 JSON 类型。可用类型为 "object"、"array"、"number"、"boolean"、"string" 和 "null"。

JSON 模式的 MongoDB 实施不支持 "integer" 类型。改用 bsonType 关键字和 "int" 或 "long" 类型。

allOf
所有类型
JSON 模式对象数组
字段必须符合所有指定的模式
anyOf
所有类型
JSON 模式对象数组
字段必须至少与一个指定模式匹配
oneOf
所有类型
JSON 模式对象数组
字段必须与至少一个指定模式匹配
not
所有类型
一个 JSON 模式对象
字段不得与模式匹配
multipleOf
数字
数字
字段必须是此值的倍数
最大值
数字
数字
指示字段的最大值
exclusiveMaximum
数字
布尔
如果为 true 并且字段是数字,则 maximum 为排他式最大值。否则为包含式最大值。
最低
数字
数字
指示字段的最小值
exclusiveMinimum
数字
布尔
如果为 true,则 minimum 为排他式最小值。否则为包含式最小值。
maxLength
字符串
整型
指示字段的最小长度
minLength
字符串
整型
指示字段的最小长度
模式
字符串
包含正则表达式的字符串
字段必须匹配正则表达式
maxProperties
对象
整型
指示字段的最小属性数量
minProperties
对象
整型
指示字段的最小属性数量
必需
对象
唯一字符串的数组
对象的属性集必须包含数组中的所有指定元素
additionalProperties
对象
布尔值或对象

如果为 true,则允许使用其他字段。如果为 false,则不允许。如果指定了有效的 JSON 模式对象,则其他字段必须根据该模式进行验证。

默认值为 true

属性
对象
对象
有效的 JSON 模式,其中每个值也是有效的 JSON 模式对象
patternProperties
对象
对象
除了 properties 要求外,该对象的每个属性名称都必须是有效的正则表达式
dependencies
对象
对象
描述字段或模式依赖项
additionalItems
数组
布尔值或对象
如果是对象,则必须是有效的 JSON 模式
商品
数组
对象或数组
必须是有效的 JSON 模式或有效 JSON 模式的数组
MaxItems
数组
整型
指示数组的最大长度
minItems
数组
整型
指示数组的最小长度
uniqueItems
数组
布尔
如果为 true,则数组中的每项都必须唯一。否则,不实施唯一性约束。
标题
不适用
字符串
没有效果的描述性标题字符串。
描述
不适用
字符串
描述模式的string ,无效。

MongoDB的 实施包括添加JSON schema bsonType关键字,它允许您在 操作符中使用所有BSON $jsonSchema类型。bsonType接受用于string $type操作符的相同 别名。

JSON 模式的 MongoDB 实施不支持以下内容:

  • JSON Schema 规范的草案 4 中的超文本定义

  • 关键字:

    • $ref

    • $schema

    • default

    • definitions

    • format

    • id

  • integer 类型。必须使用带有 bsonType 关键字的 BSON 类型 intlong

  • JSON 模式的超媒体和链接属性,包括 JSON 引用和 JSON 指针的使用。

  • 未知关键字。

后退

$expr