From 562bac5c20a52947ddd1c6adf9b350d7fdd782c7 Mon Sep 17 00:00:00 2001 From: Jeff Allen Date: Wed, 8 Sep 2021 11:24:45 -0400 Subject: [PATCH] (DOCS-14761): Validation failures include description --- source/core/schema-validation.txt | 171 ++++++++++++------ ...schema-validation-description-overview.rst | 5 + .../reference/operator/query/jsonSchema.txt | 5 +- source/release-notes/5.1.txt | 7 + 4 files changed, 136 insertions(+), 52 deletions(-) create mode 100644 source/includes/fact-5.1-schema-validation-description-overview.rst diff --git a/source/core/schema-validation.txt b/source/core/schema-validation.txt index dc64954c9c8..ad2929e62ca 100644 --- a/source/core/schema-validation.txt +++ b/source/core/schema-validation.txt @@ -144,21 +144,20 @@ query expression: :ref:`query operators ` -Behavior --------- +Behavior and Examples +--------------------- Validation occurs during updates and inserts. When you add validation to a collection, existing documents do not undergo validation checks until modification. +Validation on Existing Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To perform validation checks on existing documents, use the :dbcommand:`validate` command or the :method:`db.collection.validate()` shell helper. - -Existing Documents -~~~~~~~~~~~~~~~~~~ - The ``validationLevel`` option determines which operations MongoDB applies the validation rules: @@ -176,7 +175,7 @@ documents: .. code-block:: json - db.contacts.insert([ + db.contacts.insertMany([ { "_id": 1, "name": "Anne", "phone": "+1 555 123 456", "city": "London", "status": "Complete" }, { "_id": 2, "name": "Ivan", "city": "Vancouver" } ]) @@ -194,11 +193,11 @@ collection: properties: { phone: { bsonType: "string", - description: "must be a string and is required" + description: "phone must be a string and is required" }, name: { bsonType: "string", - description: "must be a string and is required" + description: "name must be a string and is required" } } } }, @@ -230,12 +229,12 @@ validation rule we created above that requires ``name`` to be a string. .. code-block:: javascript - db.contacts.update( + db.contacts.updateOne( { _id: 1 }, { $set: { name: 10 } } ) - db.contacts.update( + db.contacts.updateOne( { _id: 2 }, { $set: { name: 20 } } ) @@ -247,48 +246,44 @@ document did not meet the initial criteria when validation was added. .. code-block:: javascript :copyable: false - :emphasize-lines: 9-27 // _id: 1 - WriteResult({ - "nMatched" : 0, - "nUpserted" : 0, - "nModified" : 0, - "writeError" : { - "code" : 121, - "errmsg" : "Document failed validation", - "errInfo" : { - "failingDocumentId" : 1, - "details" : { - "operatorName" : "$jsonSchema", - "schemaRulesNotSatisfied" : [ + MongoServerError: Document failed validation + Additional information: { + failingDocumentId: 1, + details: { + operatorName: '$jsonSchema', + schemaRulesNotSatisfied: [ + { + operatorName: 'properties', + propertiesNotSatisfied: [ { - "operatorName" : "properties", - "propertiesNotSatisfied" : [ - { - "propertyName" : "name", - "details" : [ - { - "operatorName" : "bsonType", - "specifiedAs" : { - "bsonType" : "string" - }, - "reason" : "type did not match", - "consideredValue" : 10, - "consideredType" : "double" - } - ] - } - ] - } - ] + propertyName: 'name', + description: 'name must be a string and is required', + details: [ + { + operatorName: 'bsonType', + specifiedAs: { bsonType: 'string' }, + reason: 'type did not match', + consideredValue: 10, + consideredType: 'int' + } + ] + } + ] } - } - } - }) + ] + } + } // _id: 2 - WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) + { + acknowledged: true, + insertedId: null, + matchedCount: 1, + modifiedCount: 0, + upsertedCount: 0 + } To disable validation entirely, you can set ``validationLevel`` to ``off``. @@ -333,16 +328,13 @@ Schema validator: validationAction: "warn" } ) -With the ``warn`` :collflag:`validationAction`, MongoDB logs any -violations but allows the insertion or update to proceed. - For example, the following insert operation violates the validation rule: .. code-block:: javascript db.contacts2.insert( { name: "Amanda", status: "Updated" } ) -However, since the ``validationAction`` is ``warn`` only, MongoDB only +However, since the ``validationAction`` is ``warn``, MongoDB only logs the validation violation message and allows the operation to proceed. Run the following command to view the MongoDB logs: @@ -384,6 +376,83 @@ readability) contains information like this: \"specifiedAs\":{\"required\":[\"phone\"]}, \"missingProperties\":[\"phone\"]}]}}}}" +.. _validation-description-example: + +Use Title and Description Fields to Clarify Validation Rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-5.1-schema-validation-description-overview.rst + +Consider a ``users`` collection with the following schema validation: + +.. code-block:: javascript + + db.runCommand( { + collMod: "users", + validator: { $jsonSchema: { + bsonType: "object", + title: "Email validation", + properties: { + email: { + "bsonType": "string", + "pattern": "^@mongodb\.com$", + "description": "Email address must end with '@mongodb.com'" + }, + } + } }, + validationLevel: "moderate" + } ) + +The ``pattern`` field indicates that all ``email`` fields must +end with ``@mongodb.com``. If you try to insert a document that +does not match the pattern, MongoDB includes the validation +``title`` and ``description`` in the error output: + +Input: + +.. code-block:: javascript + + db.users.insertOne( { "name": "Amelia Morrison", "email": "a.morrison@nwsueicn.com" } ) + +Output: + +.. code-block:: javascript + :copyable: false + :emphasize-lines: 6,13 + + MongoServerError: Document failed validation + Additional information: { + failingDocumentId: ObjectId("614a10bab93bbd15dd2e2eb6"), + details: { + operatorName: '$jsonSchema', + title: 'Email validation', + schemaRulesNotSatisfied: [ + { + operatorName: 'properties', + propertiesNotSatisfied: [ + { + propertyName: 'email', + description: "Email address must end with '@mongodb.com'", + details: [ + { + operatorName: 'pattern', + specifiedAs: { pattern: '^@mongodb.com$' }, + reason: 'regular expression did not match', + consideredValue: 'a.morrison@nwsueicn.com' + } + ] + } + ] + } + ] + } + } + +.. note:: + + The validation error output is formatted differently in the legacy + ``mongo`` shell. + Restrictions ------------ diff --git a/source/includes/fact-5.1-schema-validation-description-overview.rst b/source/includes/fact-5.1-schema-validation-description-overview.rst new file mode 100644 index 00000000000..ebf21c9bb6c --- /dev/null +++ b/source/includes/fact-5.1-schema-validation-description-overview.rst @@ -0,0 +1,5 @@ +Starting in MongoDB 5.1, when a document fails :ref:`schema validation +`, MongoDB includes the validation ``title`` +and ``description`` in the error response. You can use these fields to +provide a clearer explanation of the validation when the rules +are not immediately clear, such as when using regular expressions. diff --git a/source/reference/operator/query/jsonSchema.txt b/source/reference/operator/query/jsonSchema.txt index 7dbca4a9dfa..0c49d347c26 100644 --- a/source/reference/operator/query/jsonSchema.txt +++ b/source/reference/operator/query/jsonSchema.txt @@ -489,7 +489,10 @@ Available Keywords * - description - N/A - string - - A string that describes the schema and has no effect. + - A string that describes the schema and has no effect on + validation. Starting in MongoDB 5.1, if the ``description`` field + is specified, MongoDB includes the ``description`` in the error + output when a document fails validation. .. _jsonSchema-extension: diff --git a/source/release-notes/5.1.txt b/source/release-notes/5.1.txt index 8a04e0e9675..174421b6256 100644 --- a/source/release-notes/5.1.txt +++ b/source/release-notes/5.1.txt @@ -80,6 +80,13 @@ If the new parameter the :ref:`query explain plan output `. +Schema Validation Errors Contain Description Field +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-5.1-schema-validation-description-overview.rst + +For an example, see :ref:`validation-description-example`. + .. _5.1-rel-notes-repl-sets: Replica Sets