Especificar validação de JSON schema
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
econfig
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' } ] } ] } ] } }
Dica
Por padrão, o mongosh
imprime objetos aninhados com até seis níveis de profundidade. Para imprimir todos os objetos aninhados em toda a profundidade, defina inspectDepth
como Infinity
.
config.set("inspectDepth", Infinity)
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 quelineItems.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.