/ /

Consulta y proyección

query de evaluación

Docs Home

Manual de MongoDB

Referencia

Operadores

Consulta y proyección

query de evaluación

$jsonSchema

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 5.0, consulte Procedimientos de actualización de MongoDB.6.0

Definición

$jsonSchema

El operador coincide con los documentos que satisfacen el esquema JSON $jsonSchema especificado.

La $jsonSchema expresión del operador tiene la siguiente sintaxis:

{ $jsonSchema: <JSON Schema object> }

Donde el objeto de esquema JSON está formateado de acuerdo con el 4 borrador del estándar de esquema JSON.

{ <keyword1>: <value1>, ... }

Por ejemplo:

{
  $jsonSchema: {
     required: [ "name", "major", "gpa", "address" ],
     properties: {
        name: {
           bsonType: "string",
           description: "must be a string and is required"
        },
        address: {
           bsonType: "object",
           required: [ "zipcode" ],
           properties: {
               "street": { bsonType: "string" },
               "zipcode": { bsonType: "string" }
           }
        }
     }
  }
}

Para obtener una lista de palabras clave admitidas por MongoDB, consulte Palabras clave disponibles.

Nota

MongoDB admite 4 el borrador del esquema JSON, incluyendo la especificación principal y la especificación de validación, con algunas diferencias. Consulte Extensiones y omisiones para obtener más información.

Para obtener más información sobre el esquema JSON, consulte el sitio web oficial.

Comportamiento

Compatibilidad de características

El featureCompatibilityVersion debe establecerse "3.6" en o superior para poder $jsonSchema utilizar.

Validador de documentos

Puede utilizar en un validador de documentos para aplicar el esquema especificado en las operaciones de inserción y $jsonSchema actualización:

db.createCollection( <collection>, { validator: { $jsonSchema: <schema> } } )
db.runCommand( { collMod: <collection>, validator:{ $jsonSchema: <schema> } } )

Condiciones de consulta

Puede utilizar en las condiciones de consulta para operaciones de lectura y escritura para encontrar documentos en la colección que satisfagan el esquema $jsonSchema especificado:

db.collection.find( { $jsonSchema: <schema> } )
db.collection.aggregate( [ { $match: { $jsonSchema: <schema> } } ] )
db.collection.updateMany( { $jsonSchema: <schema> }, <update> )
db.collection.deleteOne( { $jsonSchema: <schema> } )

Para encontrar documentos en la colección que no cumplan el esquema especificado, utilice la expresión $jsonSchema $nor en una expresión. Por ejemplo:

db.collection.find( { $nor: [ { $jsonSchema: <schema> } ] } )
db.collection.aggregate( [ { $match: { $nor: [ { $jsonSchema: <schema> } ] } }, ... ] )
db.collection.updateMany( { $nor: [ { $jsonSchema: <schema> } ] }, <update> )
db.collection.deleteOne( { $nor: [ { $jsonSchema: <schema> } ] } )

Ejemplos

Validación de esquema

El siguiente método crea una colección db.createCollection() llamada students y utiliza el $jsonSchema operador para establecer reglas de validación del esquema:

db.createCollection("students", {
   validator: {
      $jsonSchema: {
         bsonType: "object",
         required: [ "name", "year", "major", "address" ],
         properties: {
            name: {
               bsonType: "string",
               description: "must be a string and is required"
            },
            year: {
               bsonType: "int",
               minimum: 2017,
               maximum: 3017,
               description: "must be an integer in [ 2017, 3017 ] and is required"
            },
            major: {
               enum: [ "Math", "English", "Computer Science", "History", null ],
               description: "can only be one of the enum values and is required"
            },
            gpa: {
               bsonType: [ "double" ],
               description: "must be a double if the field exists"
            },
            address: {
               bsonType: "object",
               required: [ "city" ],
               properties: {
                  street: {
                     bsonType: "string",
                     description: "must be a string if the field exists"
                  },
                  city: {
                     bsonType: "string",
                     "description": "must be a string and is required"
                  }
               }
            }
         }
      }
   }
} )

Dado el validator creado para la colección, la siguiente operación de inserción fallará porque gpa es un entero cuando validator requiere un double.

db.students.insertOne( {
   name: "Alice",
   year: Int32( 2019 ),
   major: "History",
   gpa: Int32( 3 ),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )

La operación devuelve el siguiente error:

MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("61aa577f666a50a8fccd7ec2"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'gpa',
            description: 'must be a double if the field exists',
            details: [ [Object] ]
          }
        ]
      }
    ]
  }
}

Después de cambiar gpa a un doble, la inserción se realiza correctamente:

db.students.insertOne( {
   name: "Alice",
   year: NumberInt(2019),
   major: "History",
   gpa: Double(3.0),
   address: {
      city: "NYC",
      street: "33rd Street"
   }
} )

Condiciones de consulta

Puedes usar $jsonSchema en condiciones de query para operaciones de lectura y guardar para encontrar documentos en la colección que cumplan con el esquema especificado.

Por ejemplo, cree una colección de muestra inventory con los siguientes documentos:

db.inventory.insertMany( [
   { item: "journal", qty: NumberInt(25), size: { h: 14, w: 21, uom: "cm" }, instock: true },
   { item: "notebook", qty: NumberInt(50), size: { h: 8.5, w: 11, uom: "in" }, instock: true },
   { item: "paper", qty: NumberInt(100), size: { h: 8.5, w: 11, uom: "in" }, instock: 1 },
   { item: "planner", qty: NumberInt(75), size: { h: 22.85, w: 30, uom: "cm" }, instock: 1 },
   { item: "postcard", qty: NumberInt(45), size: { h: 10, w: 15.25, uom: "cm" }, instock: true },
   { item: "apple", qty: NumberInt(45), status: "A", instock: true },
   { item: "pears", qty: NumberInt(50), status: "A", instock: true }
] )

A continuación, defina el siguiente objeto de esquema de muestra:

let myschema =  {
      required: [ "item", "qty", "instock" ],
      properties: {
         item: { bsonType: "string" },
         qty: { bsonType: "int" },
         size: {
            bsonType: "object",
            required: [ "uom" ],
            properties: {
               uom: { bsonType: "string" },
               h: { bsonType: "double" },
               w: { bsonType: "double" }
            }
          },
          instock: { bsonType: "bool" }
      }
 }

Puede utilizar para encontrar todos los documentos de la colección que satisfacen el $jsonSchema esquema:

db.inventory.find( { $jsonSchema: myschema } )
db.inventory.aggregate( [ { $match: { $jsonSchema: myschema } } ] )

Puede utilizar $jsonSchema con para encontrar todos los documentos que no satisfacen el $nor esquema:

db.inventory.find( { $nor: [ { $jsonSchema: myschema } ] } )

O bien, puede actualizar todos los documentos que no satisfacen el esquema:

db.inventory.updateMany( { $nor: [ { $jsonSchema: myschema } ] }, { $set: { isValid: false } } )

O bien, puede eliminar todos los documentos que no cumplan con el esquema:

db.inventory.deleteMany( { $nor: [ { $jsonSchema: myschema } ] } )

JSON Schema

Para obtener más información sobre el esquema JSON, consulte el sitio web oficial.

Palabras clave disponibles

Nota

MongoDB implementa un subconjunto de palabras clave disponibles en el esquema JSON. Para obtener una lista completa de omisiones, consulte Omisiones.

Keyword	Tipo	Definición	Comportamiento
bsonType	todo tipo	alias de cadena o matriz de alias de cadena	Acepta los mismos alias de cadena `$type` utilizados para el operador
enum	todo tipo	matriz de valores	Enumera todos los valores posibles del campo
tipo	todo tipo	cadena o matriz de cadenas únicas	Enumera los posibles tipos JSON del campo. Los tipos disponibles son "objeto", "matriz", "número", "booleano", "cadena" y "null". La implementación del esquema JSON de MongoDB no admite el tipo "integer". Utilice la palabra clave `bsonType` y los tipos "int" o "long".
allOf	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir con todos los esquemas especificados
anyOf	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir con al menos uno de los esquemas especificados
uno de	todo tipo	matriz de objetos de esquema JSON	El campo debe coincidir exactamente con uno de los esquemas especificados
no	todo tipo	un objeto de esquema JSON	El campo no debe coincidir con el esquema
múltipleDe	números	Número	El campo debe ser un múltiplo de este valor
máximo	números	Número	Indica el valor máximo del campo
exclusivoMáximo	números	booleano	Si es verdadero y el campo es un número, `maximum` es un máximo exclusivo. De lo contrario, es un máximo inclusivo.
mínimo	números	Número	Indica el valor mínimo del campo
exclusivoMínimo	números	booleano	Si es verdadero, `minimum` es un mínimo exclusivo. De lo contrario, es un mínimo inclusivo.
longitud máxima	cadenas	entero	Indica la longitud máxima del campo
minLongitud	cadenas	entero	Indica la longitud mínima del campo.
patrón	cadenas	cadena que contiene una expresión regular	El campo debe coincidir con la expresión regular
maxProperties	objetos	entero	Indica el número máximo de propiedades del campo.
minPropiedades	objetos	entero	Indica el número mínimo de propiedades del campo
Requerido	objetos	matriz de cadenas únicas	El conjunto de propiedades del objeto debe contener todos los elementos especificados en la matriz
Propiedades adicionales	objetos	booleano u objeto	Si `true`, se permiten campos adicionales. Si `false`, no. Si se especifica un objeto de esquema JSON válido, los campos adicionales deben validarse con el esquema. Se establece por defecto en `true`.
propiedades	objetos	Objeto	Un esquema JSON válido donde cada valor también es un objeto de esquema JSON válido
Propiedades del patrón	objetos	Objeto	Además de los requisitos `properties`, cada nombre de propiedad de este objeto debe ser una expresión regular válida
dependencies	objetos	Objeto	Describe dependencias de campos o esquemas
artículos adicionales	matrices	booleano u objeto	Si es un objeto, debe ser un esquema JSON válido
elementos	matrices	objeto o matriz	Debe ser un esquema JSON válido o una matriz de esquemas JSON válidos
máximo de artículos	matrices	entero	Indica la longitud máxima de la matriz
minItems	matrices	entero	Indica la longitud mínima de la matriz
Artículos únicos	matrices	booleano	Si es verdadero, cada elemento de la matriz debe ser único. De lo contrario, no se aplica ninguna restricción de unicidad.
Título	N/A	string	Una string de título descriptiva sin efecto.
Descripción	N/A	string	Una cadena que describe el esquema y no tiene ningún efecto.

Extensiones

La implementación del esquema JSON de MongoDB incluye la adición de la bsonType palabra clave, que le permite utilizar todos los tipos BSON en el $jsonSchema operador. bsonType acepta los mismos alias de cadena utilizados para el $type operador.

Omisiones

Los siguientes no son compatibles con la implementación del esquema JSON de MongoDB:

Definiciones de hipertexto en 4 el borrador de la especificación del esquema JSON.
Las palabras clave:
- $ref
- $schema
- default
- definitions
- format
- id
El integer tipo. Debe utilizar el tipo BSON int o long con la bsonType palabra clave.
Propiedades de hipermedia y vinculación del esquema JSON, incluido el uso de referencias JSON y punteros JSON.
Palabras clave desconocidas.

Volver

$expr

$mod