Validación de esquema

Documentos existentes

La opción validationLevel determina en qué operaciones MongoDB aplica las reglas de validación:

• Si validationLevel es strict (por defecto), MongoDB aplica reglas de validación a todas las inserciones y actualizaciones.

• Si el validationLevel es moderate, MongoDB aplica reglas de validación a inserciones y actualizaciones de documentos existentes que ya cumplen los criterios de validación. Con el nivel moderate, las actualizaciones de los documentos existentes que no cumplen con los criterios de validación no se verifican para comprobar su validez.

Por ejemplo, crea una colección contacts con los siguientes documentos:

db.contacts.insert([
   { "_id": 1, "name": "Anne", "phone": "+1 555 123 456", "city": "London", "status": "Complete" },
   { "_id": 2, "name": "Ivan", "city": "Vancouver" }
])

Ejecuta el siguiente comando para añadir un validador a la colección contacts:

db.runCommand( {
   collMod: "contacts",
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone", "name" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         name: {
            bsonType: "string",
            description: "must be a string and is required"
         }
      }
   } },
   validationLevel: "moderate"
} )

La colección contacts ahora cuenta con un validador con el moderate nivel de validación:

• Si intentaste actualizar el documento con _id: 1, MongoDB aplicaría las nuevas reglas de validación dado que el documento existente cumple con los criterios.

• Por el contrario, MongoDB no aplicará las reglas de validación a las actualizaciones del documento con _id: 2, ya que no cumple con las reglas de validación.

A partir de MongoDB versión 5.0, el validador devuelve información detallada sobre errores cuando no se cumple una condición de validación. La salida de error es exhaustiva: se informan todos los errores, no solo el primero.

En el siguiente ejemplo, ninguna de las actualizaciones es coherente con la regla de validación que creamos anteriormente, que requiere que name sea una string.

db.contacts.update(
   { _id: 1 },
   { $set: { name: 10 } }
)
db.contacts.update(
   { _id: 2 },
   { $set: { name: 20 } }
)

La siguiente salida muestra que el documento con _id: 1 falla la validación con una explicación detallada, como se muestra en el objeto errInfo. La actualización tuvo éxito para el documento con _id: 2 ya que este documento no cumplía con los criterios iniciales cuando se añadió la validación.

// _id: 1
WriteResult({
  "nMatched" : 0,
  "nUpserted" : 0,
  "nModified" : 0,
  "writeError" : {
    "code" : 121,
    "errmsg" : "Document failed validation",
    "errInfo" : {
       "failingDocumentId" : 1,
       "details" : {
         "operatorName" : "$jsonSchema",
         "schemaRulesNotSatisfied" : [
         {
           "operatorName" : "properties",
           "propertiesNotSatisfied" : [
              {
              "propertyName" : "name",
              "details" : [
                  {
                    "operatorName" : "bsonType",
                    "specifiedAs" : {
                       "bsonType" : "string"
                        },
                    "reason" : "type did not match",
                    "consideredValue" : 10,
                    "consideredType" : "double"
                  }
                 ]
               }
             ]
           }
         ]
      }
     }
   }
})
// _id: 2
WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

Para deshabilitar completamente la validación, puede establecer validationLevel en off.

Aceptar o rechazar documentos no válidos

La opción validationAction determina cómo MongoDB gestiona los documentos que violan las reglas de validación:

• Si el validationAction es error (el valor por defecto), MongoDB rechaza cualquier inserción o actualización que viole los criterios de validación.

• Si el validationAction es warn, MongoDB registra cualquier infracción pero permite que la inserción o la actualización continúe.

Por ejemplo, crea una colección contacts2 con el siguiente validador de JSON Schema:

db.createCollection( "contacts2", {
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         email: {
            bsonType : "string",
            pattern : "@mongodb\.com$",
            description: "must be a string and match the regular expression pattern"
         },
         status: {
            enum: [ "Unknown", "Incomplete" ],
            description: "can only be one of the enum values"
         }
      }
   } },
   validationAction: "warn"
} )

Con el warn validationAction, MongoDB registra cualquier infracción pero permite que la inserción o actualización continúe.

Por ejemplo, la siguiente operación de inserción infringe la regla de validación:

db.contacts2.insertOne( { name: "Amanda", status: "Updated" } )

Sin embargo, dado que validationAction es solo warn, MongoDB únicamente registra el mensaje de infracción de validación y permite que la operación continúe. Ejecute el siguiente comando para ver los registros de MongoDB:

db.adminCommand( { getLog: "global" } )

Dependiendo del uso de la colección, este comando puede devolver gran cantidad de datos. El error de validación (una línea larga en el registro, aquí reformateada para mejorar la legibilidad) contiene información como esta:

"{\"t\":{\"$date\":\"2021-01-20T15:59:57.305+00:00\"},
 \"s\":\"W\",
 \"c\":\"STORAGE\",
 \"id\":20294,
 \"ctx\":\"conn1\",
 \"msg\":\"Document would fail validation\",
 \"attr\":{\"namespace\":\"test.contacts2\",
   \"document\":{\"_id\":{\"$oid\":\"6008537d42e0d23385568881\"},
         \"name\":\"Amanda\",
         \"status\":\"Updated\"},
    \"errInfo\":{\"failingDocumentId\":{\"$oid\":\"6008537d42e0d23385568881\"},
         \"details\":{\"operatorName\":\"$jsonSchema\",
              \"schemaRulesNotSatisfied\":[
                  {\"operatorName\":\"properties\",
                    \"propertiesNotSatisfied\":[
                        {\"propertyName\":\"status\",
                         \"details\":[
                              {\"operatorName\":\"enum\",
                               \"specifiedAs\":{\"enum\":[
                                    \"Unknown\",
                                    \"Incomplete\"]},
                          \"reason\":\"value was not found in enum\",
                          \"consideredValue\":\"Updated\"}]}]},
 {\"operatorName\":\"required\",
 \"specifiedAs\":{\"required\":[\"phone\"]},
     \"missingProperties\":[\"phone\"]}]}}}}"