/ /

Validación de esquema

Docs Home

/ /

Mejores prácticas

Validación de esquema

Validación de esquema

Especificar la validación para colecciones polimórficas

Puedes especificar la validación de esquemas para una colección que almacena datos polimórficos o documentos con estructuras o esquemas variables.

Para crear la validación de esquemas para múltiples esquemas dentro de una única colección, puedes configurar los esquemas en tus reglas de validación y asegurarte de que los documentos se ajusten a uno de los esquemas de tu colección.

Acerca de esta tarea

Considera una colección, accounts, que almacena datos sobre los clientes de un banco y los detalles de sus cuentas. La colección contiene documentos tanto de customer como de account.

El siguiente código inserta dos documentos customer en la colección accounts para almacenar los detalles de los clientes Andrew y Anne, respectivamente. También inserta dos account documentos para representar cada una de sus cuentas individuales de ahorros y un tercer account documento para representar su cuenta corriente compartida. Puedes ejecutar el código de este tutorial en el MongoDB Shell (mongosh).

db.accounts.insertMany( [
   {
      "customerId": "CUST-123456789",
      "docType": "customer",
      "name": {
         "title": "Mr",
         "first": "Andrew",
         "middle": "James",
         "last": "Morgan"
      },
      "address": {
         "street1": "240 Blackfriars Rd",
         "city": "London",
         "postCode": "SE1 8NW",
         "country": "UK"
      },
      "customerSince": ISODate("2005-05-20")
   },
   {
      "customerId": "CUST-987654321",
      "docType": "customer",
      "name": {
         "title": "Mrs",
         "first": "Anne",
         "last": "Morgan"
      },
      "address": {
         "street1": "240 Blackfriars Rd",
         "city": "London",
         "postCode": "SE1 8NW",
         "country": "UK"
      },
      "customerSince": ISODate("2003-12-01")
   },
   {
      "accountNumber": "ACC1000000654",
      "docType": "account",
      "accountType": "checking",
      "customerId": [
         "CUST-123456789",
         "CUST-987654321"
      ],
      "dateOpened": ISODate("2003-12-01"),
      "balance": Decimal128("5067.65")
   },
   {
      "accountNumber": "ACC1000000432",
      "docType": "account",
      "accountType": "savings",
      "customerId": [
         "CUST-123456789"
      ],
      "dateOpened": ISODate("2005-10-28"),
      "balance": Decimal128("10341.21")
   },
   {
      "accountNumber": "ACC1000000890",
      "docType": "account",
      "accountType": "savings",
      "customerId": [
         "CUST-987654321"
      ],
      "dateOpened": ISODate("2003-12-15"),
      "balance": Decimal128("10341.89")
   }
] );

Para permitir solo documentos que cumplan con los esquemas customer o account en la colección accounts, configure la validación del esquema utilizando el siguiente procedimiento.

Pasos

Crea una definición de esquema JSON para cada tipo de documento

Para distinguir entre diferentes tipos de documentos, puedes usar varios esquemas JSON. Para definir qué atributos deben estar en un documento y qué tipos de datos aceptan, crea dos esquemas: uno para un documento customer y otro para un documento account. Cada esquema incluye un atributo docType para identificar el tipo de entidad que representa.

const customerSchema = {
   required: ["docType", "customerId", "name", "customerSince"],
   properties: {
      docType: { enum: ["customer"] },
      customerId: { bsonType: "string"},
      name: {
            bsonType: "object",
            required: ["first", "last"],
            properties: {
               title: { enum: ["Mr", "Mrs", "Ms", "Dr"]},
               first: { bsonType: "string" },
               middle: { bsonType: "string" },
               last: { bsonType: "string" }
            }
      },
      address: {
            bsonType: "object",
            required: ["street1", "city", "postCode", "country"],
            properties: {
               street1: { bsonType: "string" },
               street2: { bsonType: "string" },
               postCode: { bsonType: "string" },
               country: { bsonType: "string" }
            }
      },
      customerSince: {
            bsonType: "date"
      }
   }
};
const accountSchema = {
   required: ["docType", "accountNumber", "accountType", "customerId", "dateOpened", "balance"],
   properties: {
      docType: { enum: ["account"] },
      accountNumber: { bsonType: "string" },
      accountType: { enum: ["checking", "savings", "mortgage", "loan"] },
      customerId: { bsonType: "array" },
      dateOpened: { bsonType: "date" },
      balance: { bsonType: "decimal" }
   }
};

Configurar la colección para aceptar solo los documentos apropiados

Para permitir documentos que coincidan con el customerSchema o el accountSchema, utiliza el operador de esquema JSON oneOf. Luego, use el comando collMod para actualizar la colección accounts que se utilizará en su validación del esquema.

db.runCommand({
   collMod: "accounts",
   validator: { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] } }
})

Agregar validaciones semánticas adicionales

Opcionalmente, puedes añadir validaciones semánticas adicionales. Por ejemplo, puedes añadir las siguientes restricciones a los documentos de tu colección:

Para los documentos customer, el valor customerSince no puede ser anterior a la hora actual.
Para los documentos account, el valor dateOpened no puede ser anterior a la hora actual.
Para las cuentas de ahorro, el balance no puede caer por debajo de cero.

Se pueden implementar las validaciones extra identificando documentos customer y account no válidos e implementando esas restricciones en la validación del esquema.

const invalidCustomer = {
   "$expr": { "$gt": ["$customerSince", "$$NOW"] }
};
const invalidAccount = {
   $or: [
      {
            accountType: "savings",
            balance: { $lt: 0}
      },
      {
            "$expr": { "$gt": ["$dateOpened", "$$NOW"]}
      }
   ]
};

const schemaValidation = {
   "$and": [
      { $jsonSchema: { oneOf: [ customerSchema, accountSchema ] }},
      { $nor: [
            invalidCustomer,
            invalidAccount
         ]
      }
   ]
};
db.runCommand({
   collMod: "accounts",
   validator: schemaValidation
})

Verifique los documentos en su colección

Para verificar que todos los documentos que ya están en tu colección cumplan con tu nueva validación de esquema, usa el comando db.collection.validate().

db.accounts.validate()

{
   ns: '66cf8508e64dbb03ce45b30e_test.accounts',
   uuid: UUID('1aedf62a-f202-4e7c-b434-879057bb6d6b'),
   nInvalidDocuments: 0,
   nNonCompliantDocuments: 0,
   nrecords: 10,
   nIndexes: 1,
   keysPerIndex: { _id_: 10 },
   indexDetails: { _id_: { valid: true } },
   valid: true,
   repaired: false,
   readTimestamp: Timestamp({ t: 1749235730, i: 26 }),
   warnings: [],
   errors: [],
   extraIndexEntries: [],
   missingIndexEntries: [],
   corruptRecords: [],
   ok: 1,
   '$clusterTime': {
      clusterTime: Timestamp({ t: 1749235753, i: 31 }),
      signature: {
         hash: Binary.createFromBase64('3h7qyhLsgU21Pnzf/KVLl8suu2I=', 0),
         keyId: Long('7449048397505364002')
      }
   },
   operationTime: Timestamp({ t: 1749235753, i: 31 })
}

nNonCompliantDocuments: 0 en la salida indica que todos los documentos de la colección accounts cumplen con los esquemas de la colección.

Pruebe su validación de esquema

Para verificar la validación de esquema, puedes probar a insertar un documento no válido en la colección accounts. Por ejemplo, intenta insertar un documento de customer sin el campo obligatorio last, para el apellido:

db.accounts.insertOne(
   {
      "docType": "customer",
      "customerId": "12345",
      "name": {
         "first": "John",
      },
      "customerSince": "2025-01-01T00:00:00Z"
   }
)

MongoServerError: Document failed validation

Volver

Realizar una query y modificar

Diseñando su esquema