As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Usando a validação do esquema JSON
Usando o operador de consulta de avaliação `$jsonSchema`, você pode validar documentos que estão sendo inseridos em suas coleções.
**Topics**
+ [Criação e uso da validação do esquema JSON](#get-started-with-validation)
+ [Palavras-chave com suporte](#json-supported-keywords)
+ [bypassDocumentValidation](#json-schema-bypass)
+ [Limitações](#json-schema-limitations)
## Criação e uso da validação do esquema JSON
### Criação de uma coleção com validação de esquema
Você pode criar uma coleção com regras de operação e validação do `createCollection`. Essas regras de validação são aplicadas durante inserções ou atualizações de documentos do Amazon DocumentDB. O exemplo de código a seguir mostra as regras de validação para uma coleção de funcionários:
```
db.createCollection("employees", {
"validator": {
"$jsonSchema": {
"bsonType": "object",
"title": "employee validation",
"required": [ "name", "employeeId"],
"properties": {
"name": {
"bsonType": "object",
"properties": {
"firstName": {
"bsonType": ["string"]
},
"lastName": {
"bsonType": ["string"]
}
},
"additionalProperties" : false
},
"employeeId": {
"bsonType": "string",
"description": "Unique Identifier for employee"
},
"salary": {
"bsonType": "double"
},
"age": {
"bsonType": "number"
}
},
"additionalProperties" : true
}
},
"validationLevel": "strict", "validationAction": "error"
} )
```
### Inserindo um documento válido
O exemplo a seguir insere documentos que estão em conformidade com as regras de validação de esquema acima:
```
db.employees.insert({"name" : { "firstName" : "Carol" , "lastName" : "Smith"}, "employeeId": "c720a" , "salary": 1000.0 })
db.employees.insert({ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24})
```
### Inserindo um documento inválido
O exemplo a seguir insere documentos que não estão em conformidade com as regras de validação de esquema acima. Neste exemplo, o valor do EmployeeID não é uma string:
```
db.employees.insert({
"name" : { "firstName" : "Carol" , "lastName" : "Smith"},
"employeeId": 720 ,
"salary": 1000.0
})
```
Este exemplo mostra a sintaxe incorreta no documento.
### Modifica uma coleção.
O comando `collMod` é usado para adicionar ou modificar as regras de validação da coleção existente. O exemplo a seguir adiciona um campo de salário à lista de campos obrigatórios:
```
db.runCommand({"collMod" : "employees",
"validator": {
"$jsonSchema": {
"bsonType": "object",
"title": "employee validation",
"required": [ "name", "employeeId", "salary"],
"properties": {
"name": {
"bsonType": "object",
"properties": {
"firstName": {
"bsonType": ["string"]
},
"lastName": {
"bsonType": ["string"]
}
},
"additionalProperties" : false
},
"employeeId": {
"bsonType": "string",
"description": "Unique Identifier for employee"
},
"salary": {
"bsonType": "double"
},
"age": {
"bsonType": "number"
}
},
"additionalProperties" : true
}
}
} )
```
### Documentos de endereçamento adicionados antes da alteração das regras de validação
Para endereçar documentos que foram adicionados à sua coleção antes da alteração das regras de validação, use os seguintes modificadores `validationLevel`:
+ **estrito**: aplica regras de validação em todas as inserções e atualizações.
+ **moderado**: aplica regras de validação a documentos válidos existentes. Durante as atualizações, os documentos inválidos existentes não são verificados.
No exemplo a seguir, depois de atualizar as regras de validação na coleção chamada “funcionários”, o campo salário é obrigatório. A atualização do seguinte documento falhará:
```
db.runCommand({
update: "employees",
updates: [{
q: { "employeeId": "c721a" },
u: { age: 25 , salary : 1000},
upsert: true }]
})
```
O Amazon DocumentDB retorna a seguinte saída:
```
{
"n" : 0,
"nModified" : 0,
"writeErrors" : [
{
"index" : 0,
"code" : 121,
"errmsg" : "Document failed validation"
}
],
"ok" : 1,
"operationTime" : Timestamp(1234567890, 1)
}
```
Atualizar o nível de validação para `moderate` permitirá que o documento acima seja atualizado com sucesso:
```
db.runCommand({
"collMod" : "employees",
validationLevel : "moderate"
})
db.runCommand({
update: "employees",
updates: [{
q: { "employeeId": "c721a" },
u: { age: 25 , salary : 1000},
upsert: true }]
})
```
O Amazon DocumentDB retorna a seguinte saída:
```
{
"n" : 1,
"nModified" : 1,
"ok" : 1,
"operationTime" : Timestamp(1234567890, 1)
}
```
### Recuperando documentos com o \$1jsonSchema
O operador `$jsonSchema` pode ser usado como filtro para consultar documentos que correspondam ao esquema JSON. Esse é um operador de nível superior que pode estar presente em documentos de filtro como um campo de nível superior ou usado com operadores de consulta, como `$and`, `$or` e `$nor`. Os exemplos a seguir mostram o uso de \$1jsonSchema como um filtro individual e com outros operadores de filtro:
Documento inserido em uma coleção de “funcionários”:
```
{ "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
{ "name" : { "firstName" : "Jane", "lastName" : "Doe" }, "employeeId" : "c721a", "salary" : 1300 }
```
Coleção filtrada somente com o operador `$jsonSchema`:
```
db.employees.find({
$jsonSchema: { required: ["age"] } })
```
O Amazon DocumentDB retorna a seguinte saída:
```
{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
```
Coleção filtrada com o operador `$jsonSchema` e outro operador:
```
db.employees.find({
$or: [{ $jsonSchema: { required: ["age", "name"]}},
{ salary: { $lte:1000}}]});
```
O Amazon DocumentDB retorna a seguinte saída:
```
{ "_id" : ObjectId("64e5f8886218c620cf0e8f8a"), "name" : { "firstName" : "Carol", "lastName" : "Smith" }, "employeeId" : "c720a", "salary" : 1000 }
{ "_id" : ObjectId("64e5f91c6218c620cf0e8f8b"), "name" : { "firstName" : "Emily", "lastName" : "Brown" }, "employeeId" : "c720b", "age" : 25, "salary" : 1050.2 }
{ "_id" : ObjectId("64e5f94e6218c620cf0e8f8c"), "name" : { "firstName" : "William", "lastName" : "Taylor" }, "employeeId" : "c721a", "age" : 24, "salary" : 1400.5 }
```
Coleção filtrada com o operador `$jsonSchema` e com o `$match` no filtro agregado:
```
db.employees.aggregate(
[{ $match: {
$jsonSchema: {
required: ["name", "employeeId"],
properties: {"salary" :{"bsonType": "double"}}
}
}
}]
)
```
O Amazon DocumentDB retorna a seguinte saída:
```
{
"_id" : ObjectId("64e5f8886218c620cf0e8f8a"),
"name" : { "firstName" : "Carol", "lastName" : "Smith" },
"employeeId" : "c720a",
"salary" : 1000
}
{
"_id" : ObjectId("64e5f91c6218c620cf0e8f8b"),
"name" : { "firstName" : "Emily", "lastName" : "Brown" },
"employeeId" : "c720b",
"age" : 25,
"salary" : 1050.2
}
{
"_id" : ObjectId("64e5f94e6218c620cf0e8f8c"),
"name" : { "firstName" : "William", "lastName" : "Taylor" },
"employeeId" : "c721a",
"age" : 24,
"salary" : 1400.5
}
{
"_id" : ObjectId("64e5f9786218c620cf0e8f8d"),
"name" : { "firstName" : "Jane", "lastName" : "Doe" },
"employeeId" : "c721a",
"salary" : 1300
}
```
### Visualizando as regras de validação existentes
Para ver as regras de validação existentes em uma coleção, use:
```
db.runCommand({
listCollections: 1,
filter: { name: 'employees' }
})
```
O Amazon DocumentDB retorna a seguinte saída:
```
{
"waitedMS" : NumberLong(0),
"cursor" : {
"firstBatch" : [
{
"name" : "employees",
"type" : "collection",
"options" : {
"autoIndexId" : true,
"capped" : false,
"validator" : {
"$jsonSchema" : {
"bsonType" : "object",
"title" : "employee validation",
"required" : [
"name",
"employeeId",
"salary"
],
"properties" : {
"name" : {
"bsonType" : "object",
"properties" : {
"firstName" : {
"bsonType" : [
"string"
]
},
"lastName" : {
"bsonType" : [
"string"
]
}
},
"additionalProperties" : false
},
"employeeId" : {
"bsonType" : "string",
"description" : "Unique Identifier for employee"
},
"salary" : {
"bsonType" : "double"
},
"age" : {
"bsonType" : "number"
}
},
"additionalProperties" : true
}
},
"validationLevel" : "moderate",
"validationAction" : "error"
},
"info" : {
"readOnly" : false
},
"idIndex" : {
"v" : 2,
"key" : {
"_id" : 1
},
"name" : "_id_",
"ns" : "test.employees"
}
}
],
"id" : NumberLong(0),
"ns" : "test.$cmd.listCollections"
},
"ok" : 1,
"operationTime" : Timestamp(1692788937, 1)
}
```
O Amazon DocumentDB também mantém as regras de validação no estágio de agregação de `$out`.
## Palavras-chave com suporte
Os seguintes campos são compatíveis com os comandos `create` e `collMod`:
+ **`Validator`** — Oferece suporte ao operador `$jsonSchem`.
+ **`ValidationLevel`** — Oferece suporte aos valores `off`, `strict` e `moderate`.
+ **`ValidationAction`** — Oferece suporte ao valor `error`.
O operador \$1jsonSchema é compatível com as seguintes palavras-chave:
+ `additionalItems`
+ `additionalProperties`
+ `allOf`
+ `anyOf`
+ `bsonType`
+ `dependencies`
+ `description`
+ `enum`
+ `exclusiveMaximum`
+ `exclusiveMinimum`
+ `items`
+ `maximum`
+ `minimum`
+ `maxItems`
+ `minItems`
+ `maxLength`
+ `minLength`
+ `maxProperties`
+ `minProperties`
+ `multipleOf`
+ `not`
+ `oneOf`
+ `pattern`
+ `patternProperties`
+ `properties`
+ `required`
+ `title`
+ `type`
+ `uniqueItems`
## bypassDocumentValidation
O Amazon DocumentDB oferece suporte a `bypassDocumentValidation` para os seguintes comandos e métodos:
+ `insert`
+ `update`
+ `findAndModify`
+ Estágio `$out` no comando `aggregate` e no método `db.collection.aggregate()`
O Amazon DocumentDB não oferece suporte aos seguintes comandos para `bypassDocumentValidation`:
+ `$merge` no comando `aggregate` e no método `db.collection.aggregate()`
+ Comando `mapReduce` e método `db.collection.mapReduce()`
+ Comando `applyOps`
## Limitações
As limitações a seguir se aplicam à validação `$jsonSchema`:
+ O Amazon DocumentDB retorna o erro “Falha na validação do documento” quando uma operação falha na regra de validação.
+ Os clusters elásticos do Amazon DocumentDB não suportam `$jsonSchema`.