/ /

Query & proyección

query de evaluación

Docs Home

Manual de MongoDB

$jsonSchema

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 5.0, consulta el Procedimientos de actualización de MongoDB 6.0 .

Definición

$jsonSchema

El operador $jsonSchema coincide con documentos que cumplen el JSON schema especificado.

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

{ $jsonSchema: <JSON Schema object> }

Donde el JSON schema está formateado según el borrador 4 del estándar de JSON schema.

{ <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 una lista de las palabras clave compatibles con MongoDB, consulte Palabras clave disponibles.

Nota

MongoDB es compatible con el borrador 4 de JSON Schema, incluyendo especificación principal y especificación de validación, con algunas diferencias. Consulta Extensiones y Omisiones para obtener más detalles.

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

Comportamiento

Compatibilidad de características

La featureCompatibilityVersion debe establecerse en "3.6" o superior para poder usar $jsonSchema.

Validador de Documentos

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

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

Condiciones de query

Puedes utilizar $jsonSchema en las condiciones de query para las operaciones de lectura y escritura para encontrar documentos en la colección que cumplan el esquema especificado:

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

Para buscar documentos en la colección que no cumplan con el esquema especificado, utiliza la expresión $jsonSchema en una expresión $nor. 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 db.createCollection() crea una colección llamada students y usa el operador $jsonSchema para establecer reglas de validación de 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 el 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 el gpa a un double, la inserción es exitosa:

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

Condiciones de query

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, crea 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, siguiente, define 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 $jsonSchema para encontrar todos los documentos en la colección que cumplan con el esquema:

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

Puedes usar $jsonSchema con el $nor para encontrar todos los documentos que no cumplen con el esquema:

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

O bien, puedes actualizar todos los documentos que no satisfagan el esquema:

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

O puedes borrar todos los documentos que no cumplan con el esquema:

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

JSON Schema

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

Palabras clave disponibles

Nota

MongoDB implementa un subconjunto de palabras clave disponibles en JSON Schema. Para una lista completa de omisiones, consulta Omisiones.

Keyword	Tipo	Definición	Comportamiento
bsonType	todo tipo	string alias o arreglo de alias de string	Acepta los mismos alias de string utilizados para el operador `$type`
enum	todo tipo	arreglo de valores	Enumera todos los valores posibles del campo
tipo	todo tipo	string o arreglo de cadenas únicas	Enumera los posibles tipos JSON del campo. Los tipos disponibles son "objeto", "arreglo", "número", "booleano", "string" y "nulo". La implementación de MongoDB del esquema JSON no admite el tipo "entero". Utilza la palabra clave `bsonType` y los tipos "int" o "long" en su lugar.
allOf	todo tipo	arreglo de objetos de JSON Schema	El campo debe coincidir con todos los esquemas especificados
anyOf	todo tipo	arreglo de objetos de JSON Schema	El campo debe coincidir con al menos uno de los esquemas especificados
unoDe	todo tipo	arreglo de objetos de JSON Schema	El campo debe coincidir exactamente con uno de los esquemas especificados
no	todo tipo	un objeto de JSON Schema	El campo no debe coincidir con el esquema
multipleOf	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
ExclusiveMaximum	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
exclusiveMinimum	Números	booleano	Si es verdadero, `minimum` es un valor mínimo exclusivo. En caso contrario, se trata de un mínimo inclusivo.
maxLength	Cuerdas	entero	Indica la longitud máxima del campo
minLength	Cuerdas	entero	Indica la longitud mínima del campo
Patrón	Cuerdas	string que contiene una expresión regular	El campo debe coincidir con la expresión regular
maxProperties	objeto	entero	Indica el número máximo de propiedades del campo
minProperties	objeto	entero	Indica el número mínimo de propiedades del campo
Requerido	objeto	arreglo de cadenas únicas	El conjunto de propiedades del objeto debe contener todos los elementos especificados en el arreglo
Propiedades adicionales	objeto	Booleano o objeto	Si `true`, están permitidos campos adicionales. Si `false`, no lo son. Si se especifica un objeto JSON Schema válido, los campos adicionales deben validarse según el esquema. Se establece por defecto en `true`.
Propiedades	objeto	Objeto	Un esquema JSON válido donde cada valor también sea un objeto JSON Schema válido
patternProperties	objeto	Objeto	Además de los requisitos de `properties`, cada nombre de propiedad de este objeto debe ser una expresión regular válida
dependencies	objeto	Objeto	Describe las dependencias de campos o esquemas
itemsAdicionales	Arreglos	Booleano o objeto	Si es un objeto, debe ser un JSON Schema válido
elementos	Arreglos	objeto o arreglo	Debe ser un JSON Schema válido o un arreglo de JSON Schemas válidos.
maxItems	Arreglos	entero	Indica la longitud máxima del arreglo
minÍtems	Arreglos	entero	Indica la longitud mínima del arreglo
uniqueItems	Arreglos	booleano	Si es verdadero, cada elemento del arreglo 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 string que describe el esquema y no tiene efecto.

Extensiones

La implementación de MongoDB de JSON Schema incluye la adición de la palabra clave bsonType, que permite usar todos los tipos de BSON en el operador $jsonSchema. bsonType acepta los mismos alias de string que se utilizan para el operador $type.

Omisiones

Lo siguiente no es compatible con la implementación de MongoDB de JSON Schema:

Definiciones de hipervínculo en el borrador 4 de la especificación JSON Schema.
Las palabras clave:
- $ref
- $schema
- default
- definitions
- format
- id
El tipo integer . Se debe utilizar el tipo BSON int o long con la palabra clave bsonType.
Hipermedia y propiedades de enlace de JSON Schema, incluido el uso de referencias JSON y punteros JSON.
Palabras clave desconocidas.

Volver

$expr

$mod