Cómo utilizar la validación de esquemas JSON - Amazon DocumentDB
Cómo crear y utilizar la validación de esquemas JSONPalabras clave compatiblesbypassDocumentValidationLimitaciones

Cómo utilizar la validación de esquemas JSON

Con el operador de consulta de evaluación de $jsonSchema, puede validar los documentos que se están insertando en sus colecciones.

Cómo crear y utilizar la validación de esquemas JSON

Cómo crear una colección con validación de esquemas

Puede crear una colección con reglas de operación y validación de createCollection. Estas reglas de validación se aplican al insertar o actualizar documentos de Amazon DocumentDB. En el siguiente ejemplo de código se muestran las reglas de validación para un conjunto de empleados:

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

Cómo insertar un documento válido

En el siguiente ejemplo, se insertan documentos que cumplen con las reglas de validación de esquemas anteriores:

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

Cómo insertar un documento no válido

En el siguiente ejemplo, se insertan documentos que no cumplen con las reglas de validación de esquemas anteriores. En este ejemplo, el valor employeeId no es una cadena:

db.employees.insert({
    "name" : { "firstName" : "Carol" , "lastName" : "Smith"}, 
    "employeeId": 720 , 
    "salary": 1000.0 
})

En este ejemplo, se muestra una sintaxis incorrecta en el documento.

Modificación de una colección

El comando collMod se utiliza para añadir o modificar las reglas de validación de la colección existente. En el siguiente ejemplo se añade un campo de salario a la lista de campos obligatorios:

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

Cómo abordar los documentos añadidos antes de que se cambiaran las reglas de validación

Para abordar los documentos que se añadieron a su colección antes de que se cambiaran las reglas de validación, utilice los siguientes modificadores de validationLevel:

  • estricto: aplica reglas de validación a todas las inserciones y actualizaciones.

  • moderado: aplica reglas de validación a los documentos válidos existentes. Durante las actualizaciones, no se comprueban los documentos no válidos existentes.

En el siguiente ejemplo, tras actualizar las reglas de validación de la colección denominada “empleados”, el campo de salario es obligatorio. No se podrá actualizar el siguiente documento:

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }] 
})

Amazon DocumentDB devuelve el siguiente resultado:

{
"n" : 0,
    "nModified" : 0,
    "writeErrors" : [
        {
"index" : 0,
            "code" : 121,
            "errmsg" : "Document failed validation"
        }
    ],
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

Si se actualiza el nivel de validación a moderate, se permitirá actualizar el documento anterior correctamente:

db.runCommand({
    "collMod" : "employees", 
    validationLevel : "moderate"
})

db.runCommand({ 
    update: "employees", 
    updates: [{ 
        q: { "employeeId": "c721a" }, 
        u: { age: 25 , salary : 1000}, 
        upsert: true }]
})

Amazon DocumentDB devuelve el siguiente resultado:

{
"n" : 1,
    "nModified" : 1,
    "ok" : 1,
    "operationTime" : Timestamp(1234567890, 1)
}

Recuperación de documentos con el $jsonSchema

El operador de $jsonSchema se puede utilizar como filtro para consultar documentos que coincidan con el esquema JSON. Se trata de un operador de nivel superior que puede estar presente en los documentos de filtro como campo de nivel superior o utilizarse con operadores de consulta como $and, $or y $nor. En los siguientes ejemplos se muestra el uso de $jsonSchema como filtro individual y con otros operadores de filtro:

Documento insertado en una colección de “empleado”:

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

Colección filtrada únicamente con el operador de $jsonSchema:

db.employees.find({ 
       $jsonSchema: { required: ["age"] } })

Amazon DocumentDB devuelve el siguiente resultado:

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

Colección filtrada con el operador de $jsonSchema y otro operador:

db.employees.find({ 
       $or: [{ $jsonSchema: { required: ["age", "name"]}}, 
            { salary: { $lte:1000}}]});

Amazon DocumentDB devuelve el siguiente resultado:

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

Colección filtrada con el operador de $jsonSchema y con $match en el filtro de agregación:

db.employees.aggregate(
    [{ $match: { 
        $jsonSchema: { 
            required: ["name", "employeeId"],  
            properties: {"salary" :{"bsonType": "double"}}
        }
       }
    }]
)

Amazon DocumentDB devuelve el siguiente resultado:

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

Cómo visualizar las reglas de validación existentes

Para ver las reglas de validación existentes en una colección, utilice:

db.runCommand({
    listCollections: 1, 
    filter: { name: 'employees' }
})

Amazon DocumentDB devuelve el siguiente resultado:

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

Amazon DocumentDB también conserva las reglas de validación en la etapa de agregación $out.

Palabras clave compatibles

Los comandos create y collMod admiten los siguientes campos:

  • Validator: admite el operador $jsonSchema.

  • ValidationLevel: admite los valores off, strict y moderate.

  • ValidationAction: admite el valor error.

El operador $jsonSchema admite las siguientes palabras clave:

  • 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

Amazon DocumentDB admite bypassDocumentValidation para los siguientes comandos y métodos:

  • insert

  • update

  • findAndModify

  • Etapa $out en el comando aggregate y en el método db.collection.aggregate()

Amazon DocumentDB no admite los siguientes comandos para bypassDocumentValidation:

  • $merge en el comando aggregate y en el método db.collection.aggregate()

  • Comando mapReduce y método db.collection.mapReduce()

  • applyOps command

Limitaciones

Las siguientes limitaciones se aplican a la validación de $jsonSchema:

  • Amazon DocumentDB devuelve el error “No se pudo validar el documento” cuando una operación no cumple con la regla de validación.

  • Los clústeres elásticos de Amazon DocumentDB no admiten $jsonSchema.