$jsonSchema

Nesta página

Definição

Comportamento
Exemplos
JSON schema

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualização.

Definição

$jsonSchema

O operador $jsonSchema corresponde a documentos que satisfazem o JSON schema especificado.

A expressão do operador $jsonSchema tem a seguinte sintaxe:

{ $jsonSchema: <JSON Schema object> }

Quando o objeto de JSON schema é formatado de acordo com o rascunho 4 do padrão de JSON schema.

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

Por exemplo:

{
  $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" }
           }
        }
     }
  }
}

Para obter uma lista de palavras-chave suportadas pelo MongoDB, consulte Palavras-chave disponíveis.

Observação

O MongoDB suporta o 4 rascunho do JSON schema, incluindo a especificação principal e especificação de validação , com algumas diferenças. Consulte Extensões e Omissões para obter detalhes.

Para mais informações sobre JSON schema, consulte o site oficial.

Comportamento

Compatibilidade de recursos

OfeatureCompatibilityVersion deve ser definido como "3.6" superior para usar o $jsonSchema.

Validador de documentos

Você pode usar $jsonSchema em um validador de documento para impor o esquema especificado nas operações de inserção e atualização:

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

Condições de query

Você pode usar $jsonSchema em condições de query para operações de leitura e gravação para localizar documentos na coleção que satisfaçam o esquema especificado:

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

Para localizar documentos na coleção que não satisfazem o esquema especificado, utilize a expressão $jsonSchema em uma expressão $nor . Por exemplo:

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

Exemplos

Validação de esquema

O método db.createCollection() a seguir cria uma collection chamada students e usa o operador $jsonSchema para definir regras de validação de esquema:

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"
                  }
               }
            }
         }
      }
   }
} )

Dado o validator criado para a collection, a seguinte operação de inserção falhará porque gpa é um número inteiro quando o validator exige um double.

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

A operação retorna o seguinte erro:

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

Depois de alterar o gpa para um duplo, a inserção é bem-sucedida:

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

Condições de query

Você pode usar $jsonSchema em condições de query para operações de leitura e gravação para localizar documentos na coleção que satisfaçam o esquema especificado.

Por exemplo, criar uma collection de amostra inventory com os seguintes documentos:

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

Em seguida, defina o seguinte objeto de esquema de exemplo:

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" }
      }
 }

Você pode utilizar o $jsonSchema para encontrar todos os documentos na coleção que satisfazem o esquema:

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

Você pode usar $jsonSchema com $nor para encontrar todos os documentos que não satisfazem o esquema:

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

Ou você pode atualizar todos os documentos que não satisfazem o esquema:

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

Ou você pode excluir todos os documentos que não satisfazem o esquema:

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

JSON schema

O MongoDB suporta o 4 rascunho do JSON schema, incluindo a especificação principal e especificação de validação , com algumas diferenças. Consulte Extensões e Omissões para obter detalhes.

Para mais informações sobre JSON schema, consulte o site oficial.

Palavras-chave disponíveis

Observação

O MongoDB implementa um subconjunto de palavras-chave disponíveis no JSON schema. Para obter uma lista completa das omissões, consulte Omissões.

Keyword	Tipo	Definição	Comportamento
bsonType	todos os tipos	alias de string ou array de aliases de string	Aceita os mesmos aliases de string usados para o operador `$type`
enum	todos os tipos	array de valores	Enumera todos os valores possíveis do campo
type	todos os tipos	string ou array de strings exclusivas	Enumera os possíveis tipos de JSON do campo. Os tipos disponíveis são "object", "array", "number", "boolean", "string" e "null". A implementação do JSON schema do MongoDB não oferece suporte ao tipo "integer". Use a palavra-chave `bsonType` e os tipos "int" ou "long".
allOf	todos os tipos	array de objetos de JSON schema	O campo deve corresponder a todos os esquemas especificados
anyOf	todos os tipos	array de objetos de JSON schema	O campo deve corresponder a pelo menos um dos esquemas especificados
oneOf	todos os tipos	array de objetos de JSON schema	O campo deve corresponder exatamente a um dos esquemas especificados
não	todos os tipos	um objeto de JSON schema	O campo não deve corresponder ao esquema
multipleOf	números	número	O campo deve ser um múltiplo deste valor
maximum	números	número	Indica o valor máximo do campo
exclusiveMaximum	números	booleano	Se true e campo for um número, `maximum` é um máximo exclusivo. Caso contrário, é um máximo inclusivo.
minimum	números	número	Indica o valor mínimo do campo
exclusiveMinimum	números	booleano	Se true, `minimum` é um mínimo exclusivo. Caso contrário, é um mínimo inclusivo.
maxLength	strings	inteiro	Indica o comprimento máximo do campo
minLength	strings	inteiro	Indica o comprimento mínimo do campo
padrão	strings	string que contém um regex	O campo deve corresponder à expressão regular
maxProperties	objetos	inteiro	Indica o número máximo de propriedades do campo
minProperties	objetos	inteiro	Indica o número mínimo de propriedades do campo
necessário	objetos	array de strings exclusivas	O conjunto de propriedades do objeto deve conter todos os elementos especificados na array
Propriedades adicionais	objetos	booleano ou objeto	Se `true`, são permitidos campos adicionais. Se `false`, não são. Se um objeto de JSON schema válido for especificado, campos adicionais deverão ser validados em relação ao esquema. Padrão é `true`.
properties	objetos	objeto	Um JSON schema válido onde cada valor também é um objeto de JSON schema válido
patternProperties	objetos	objeto	Além dos requisitos de `properties`, cada nome de propriedade deste objeto deve ser uma expressão regular válida
dependencies	objetos	objeto	Descreve dependências de campo ou esquema
additionalItems	arrays	booleano ou objeto	Se for um objeto, deve ser um JSON schema válido
items	arrays	objeto ou array	Deve ser um JSON schema válido ou uma array de JSON schemas válidos
maxItems	arrays	inteiro	Indica o comprimento máximo da array
minItems	arrays	inteiro	Indica o comprimento mínimo da array
uniqueItems	arrays	booleano	Se true, cada item na array deverá ser exclusivo. Caso contrário, nenhuma restrição de exclusividade será imposta.
title	N/A	string	Uma string de título descritiva sem efeito.
Descrição	N/A	string	Uma string que descreve o esquema e não tem efeito.

Extensões

A implementação do JSON schema do MongoDB inclui a adição da palavra-chave bsonType , que permite usar todos os tipos BSON no operador $jsonSchema . bsonType aceita os mesmos aliases de string usados para o operador $type .

Omissões

O seguinte não é permitido na implementação do JSON schema do MongoDB:

Definições de hipertexto no rascunho 4 da especificação do JSON schema.
As palavras-chave:
- $ref
- $schema
- default
- definitions
- format
- id
O tipo integer. Você deve usar o tipo BSON int ou long com a palavra-chave bsonType.
Hipermídia e propriedades de vinculação do JSON schema, incluindo o uso de referências JSON e ponteiros JSON.
Palavras-chave desconhecidas.

Voltar

$expr

$mod