$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 } ] } )

JSON schema

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 类型 int 或 long。
JSON 模式的超媒体和链接属性，包括 JSON 引用和 JSON 指针的使用。
未知关键字。

后退

$expr

来年

$mod