Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ /

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.

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

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.

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.

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

1

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.

2

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.

3

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)
4

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

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.

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.

Voltar

Validação de esquema