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