Especificar validação de JSON schema

Nesta página

Compatibilidade

Contexto
Restrições
Passos
Informações adicionais
Saiba mais

JSON schema é um vocabulário que permite que você anote e valide documentos JSON. Você pode utilizar JSON schema para especificar regras de validação para seus campos em um formato legível por humanos.

Compatibilidade

Você pode utilizar a validação de JSON schema para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Contexto

O MongoDB é compatível com o rascunho 4 do JSON schema, incluindo a especificação principal e a especificação de validação, com algumas diferenças. Para obter detalhes, consulte Extensões e Omissões.

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

Restrições

Você não pode especificar a validação de esquema para:

Collections nos bancos de dados admin, local e config
Collections do sistema

Se você tiver a Client-Side Field Level Encryption ou a Queryable Encryption habilitadas em uma coleção, a validação estará sujeita às seguintes restrições:

Para CSFLE, ao executar collMod, a biblioteca libmongocrypt prefere o esquema de criptografia JSON especificado no comando. Isso permite definir um esquema em uma coleção que ainda não tem um.
Na Queryable Encryption, qualquer JSON schema que inclua um campo criptografado resulta em um erro de análise de consulta.

Passos

Neste exemplo, você cria uma coleta students com regras de validação e observa os resultados após tentar inserir um documento inválido.

Conecte-se à sua MongoDB deployment.

Para conectar a uma instância local do MongoDB ou implantação do MongoDB Atlas utilizando o mongosh, consulte as etapas em Conectar a uma implantação ou Conectar via mongosh.

Crie uma coleta com validação.

No mongosh, execute o seguinte comando para criar uma coleção students e use o operador $jsonSchema para definir regras de validação de esquema:

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         title: "Student Object Validation",
         required: [ "address", "major", "name", "year" ],
         properties: {
            name: {
               bsonType: "string",
               description: "'name' must be a string and is required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               description: "'year' must be an integer in [ 2017, 3017 ] and is required"
            },
            gpa: {
               bsonType: [ "double" ],
               description: "'gpa' must be a double if the field exists"
            }
         }
      }
   }
} )

Dica

Esclareça regras com campos de título e descrição

Você pode utilizar os campos title e description para fornecer uma explicação das regras de validação quando as regras não forem imediatamente claras. Quando um documento falha na validação, o MongoDB inclui esses campos na saída de erro.

Confirme se a validação impede documentos inválidos.

Execute o seguinte comando. A operação de inserção falha, pois 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"
   }
} )

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("630d093a931191850b40d0a9"),
  details: {
    operatorName: '$jsonSchema',
    title: 'Student Object Validation',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'gpa',
            description: "'gpa' must be a double if the field exists",
            details: [
              {
                operatorName: 'bsonType',
                specifiedAs: { bsonType: [ 'double' ] },
                reason: 'type did not match',
                consideredValue: 3,
                consideredType: 'int'
              }
            ]
          }
        ]
      }
    ]
  }
}

Insert a valid document.

Se você alterar o valor do campo gpa para um tipo double, a operação de inserção será bem-sucedida. Execute o seguinte comando para inserir o documento válido:

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

Consulte o documento válido.

Para confirmar que você inseriu o documento com sucesso, execute o seguinte comando para consultar a collection students:

db.students.find()

[
   {
      _id: ObjectId("62bb413014b92d148400f7a5"),
      name: 'Alice',
      year: 2019,
      major: 'History',
      gpa: 3,
      address: { city: 'NYC', street: '33rd Street' }
   }
]

Dica

Se você estiver conectado a uma implantação do Atlas, também poderá visualizar e filtrar o documento na UI do Atlas.

Informações adicionais

Você pode combinar a validação de JSON schema com a validação do operador de query.

Por exemplo, considere uma collection sales com esta validação de esquema:

 db.createCollection("sales", {
   validator: {
     "$and": [
       // Validation with query operators
       {
         "$expr": {
           "$lt": ["$lineItems.discountedPrice", "$lineItems.price"]
         }
       },
       // Validation with JSON Schema
       {
         "$jsonSchema": {
           "properties": {
             "items": { "bsonType": "array" }
           }
          }
        }
      ]
    }
  }
)

A validação anterior força que os documentos na collection sales sigam estas regras:

lineItems.discountedPrice deve ser menor que lineItems.price. Esta regra é especificada utilizando o operador $lt.
O campo items deve ser uma matriz. Esta regra é especificada utilizando $jsonSchema.

Saiba mais

Para ver a lista completa de palavras-chave permitidas em um JSON schema, consulte Palavras-chave disponíveis.
Para restringir quais valores um determinado campo pode conter, consulte Especificar valores de campo permitidos.
Para evitar problemas com a validação de JSON schema, consulte Dicas para a validação de JSON schema.

Voltar

Validação de esquema

Especifique valores de campo