DOCSP-31848: Schema validation (#34)

Author: norareidy

source/fundamentals.txt

@@ -9,21 +9,22 @@ Fundamentals
    :maxdepth: 1
 
    /fundamentals/connections
-   /fundamentals/stable-api
    /fundamentals/authentication
    /fundamentals/crud
-   /fundamentals/database-collection
+   /fundamentals/schema-validation
    /fundamentals/aggregation
-   /fundamentals/tracing-logging
    /fundamentals/run-command
 
 ..
    Connect to MongoDB Atlas from AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
+   /fundamentals/stable-api
    /fundamentals/context
+   /fundamentals/auth
    /fundamentals/enterprise-auth
    /fundamentals/bson
    /fundamentals/indexes
    /fundamentals/transactions
+   /fundamentals/logging
    /fundamentals/collations
    /fundamentals/monitoring
    /fundamentals/gridfs

source/fundamentals/crud/write-operations/change.txt

@@ -338,7 +338,7 @@ the options available in ``UpdateOptions``:
    * - ``bypass_document_validation``
      - | If ``true``, allows the driver to perform a write that violates
          document-level validation. To learn more about validation, see
-         :manual:`Schema Validation </core/schema-validation>` in the Server manual.
+         the guide on :ref:`rust-schema-validation`.
 
        | Type: ``bool``
        | Default: ``false``

source/fundamentals/crud/write-operations/insert.txt

@@ -104,7 +104,7 @@ following table describes the options available in
    * - ``bypass_document_validation``
      - | If ``true``, allows the driver to perform a write that violates
          document-level validation. To learn more about validation, see
-         :manual:`Schema Validation </core/schema-validation>` in the Server manual.
+         the guide on :ref:`rust-schema-validation`.
 
        | Type: ``bool``
        | Default: ``false``
@@ -124,6 +124,8 @@ following table describes the options available in
 
        | Type: ``Bson``
 
+.. _rust-insertone-bypass-validation-ex:
+
 The following code shows how to construct an ``InsertOneOptions``
 instance:
 
@@ -191,7 +193,7 @@ following table describes the options available in
    * - ``bypass_document_validation``
      - | If ``true``, allows the driver to perform a write that violates
          document-level validation. To learn more about validation, see
-         :manual:`Schema Validation </core/schema-validation>` in the Server manual.
+         the guide on :ref:`rust-schema-validation`.
 
        | Type: ``bool``
        | Default: ``false``

source/fundamentals/schema-validation.txt

@@ -0,0 +1,195 @@
+.. _rust-schema-validation:
+
+==================
+Schema Validation
+==================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} to implement
+**schema validation** for your MongoDB collections.
+
+To implement schema validation, you must provide a JSON schema that consists
+of a set of a validation rules. If you implement schema validation, the
+server only allows you to run write operations that follow the validation
+rules. Use schema validation to restrict data types and value ranges of
+document fields in a specified collection. 
+
+You can define schema validation rules when creating a collection by using
+driver methods, or you can add them to an existing collection by using the
+``collMod`` MongoDB command. This guide only describes how to enable schema
+validation when creating a collection. To learn more about enabling schema
+validation on existing collections, see :manual:`collMod </reference/command/collMod/>`
+in the Server manual.
+
+.. _rust-json-validation:
+
+JSON Schema Validation
+----------------------
+
+Before creating a collection with schema validation rules, you must define a
+JSON schema.
+
+The JSON schema is a JSON object that contains key-value pairs specifying
+the validation rules for your collection. At the top level, this object must
+include a ``$jsonSchema`` object. The ``$jsonSchema`` object includes the
+following fields:
+
+- **title**: sets an optional description for the schema.
+- **required**: specifies a list of required fields for each document in
+  your collection.
+- **properties**: sets property requirements for individual fields.
+
+For a full list of JSON schema object fields, see :manual:`JSON Schema
+</reference/operator/query/jsonSchema/#json-schema>` in the Server manual.
+
+Implement Schema Validation
+---------------------------
+
+You can implement schema validation by passing your schema and related options
+in an instance of ``CreateCollectionOptions`` to the ``create_collection()``
+method. You can build a ``CreateCollectionOptions`` instance by using the
+``CreateCollectionOptions::builder()`` method.
+
+Call the following ``CreateCollectionOptions::builder()`` functions to specify
+the validation options for the new collection:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Method
+     - Description
+
+   * - ``validator()``
+     - Specifies validation rules for a collection by passing a JSON schema.
+       
+       For more information, see the :ref:`<rust-json-validation>`
+       section on this page.
+       
+   * - ``validation_level()``
+     - Specifies which insert and update operations are subject to the validation
+       rules. 
+
+       Possible values: ``ValidationLevel::Off``,
+       ``ValidationLevel::Strict``, ``ValidationLevel::Moderate``.
+
+   * - ``validation_action()``
+     - Specifies whether the driver throws an error or a warning if you insert documents
+       that don't follow the validation rules.
+
+       Possible values: ``ValidationAction::Error``, ``ValidationAction::Warn``.
+
+Example
+~~~~~~~
+
+This example creates a collection called ``survey_answers`` with the
+following validation specifications:
+
+- The ``validator()`` method recieves a JSON schema specifying that the
+  ``answer`` field in each document must have a value of ``"yes"`` or
+  ``"no"``.
+- The ``validation_action()`` method specifies whether the driver raises an
+  ``Error`` when a write operation violates a validation rule.
+- The ``validation_level()`` method specifies that the validation is
+  ``Moderate``, so the validation rules apply only to inserts and
+  updates on existing valid documents.
+
+.. literalinclude:: /includes/fundamentals/code-snippets/schema-validation.rs
+   :language: rust
+   :dedent:
+   :start-after: begin-schema-validation
+   :end-before: end-schema-validation
+
+The following documents follow the validation rules and can be successfully
+inserted:
+
+.. code-block:: json
+   :copyable: false
+   :emphasize-lines: 4, 9
+
+   {
+     "_id": { ... },
+     "question": "Do you like to exercise?",
+     "answer": "yes"
+   },
+   {
+     "_id": { ... },
+     "question": "Do you like to play computer games?",
+     "answer": "no"
+   }
+
+However, if you attempt to insert the following document, the server
+raises an error because the value of ``answer`` does not match any of
+the valid options:
+
+.. io-code-block::
+   :copyable: false
+
+   .. input::
+      :language: json
+      :emphasize-lines: 4
+
+      {
+        "_id": { ... },
+        "question": "Do you like to exercise?",
+        "answer": "depends on my mood"
+      }
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Error: Error { kind: Write(WriteError(WriteError { code: 121, code_name:
+      None, message: "Document failed validation", details:
+      Some(Document({"failingDocumentId":
+      ObjectId("..."), "details":
+      Document({"operatorName": String("$jsonSchema"), "title": String("Answer
+      Value Validation"), ... })})) })), ... }
+
+.. tip:: Bypass Schema Validation
+   
+   To bypass a collection's validation rules, set the ``bypass_document_validation``
+   field to ``true`` in the write method's options parameter. This ignores any validation
+   rules on the collection and any exemptions of them defined by the ``validation_level``.
+   
+   To see an example of how to specify this setting in the options for the
+   ``insert_one()`` method, see the :ref:`Modify insert_one Behavior
+   <rust-insertone-bypass-validation-ex>` section of the Insert Documents guide.
+
+Additional Information
+----------------------
+
+To learn more about the MongoDB Server operations mentioned on this page,
+see the following Server manual documentation:
+
+- :manual:`Validation operations for the collMod command </reference/command/collMod/#validate-documents>`
+- :manual:`Schema Validation </core/schema-validation/>`
+- :manual:`Specify JSON Schema Validation </core/schema-validation/specify-json-schema/#std-label-schema-validation-json>`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about setting validation levels and actions, see the
+following API Documentation:
+
+- `validation_level <{+api+}/options/struct.CreateCollectionOptions.html#structfield.validation_level>`__ 
+  for the ``validation_level()`` helper method
+- `ValidationLevel <{+api+}/options/enum.ValidationLevel.html>`__ for possible ``validation_level`` values
+- `validation_action <{+api+}/options/struct.CreateCollectionOptions.html#structfield.validation_action>`__
+  for the ``validation_action()`` helper method
+- `ValidationAction <{+api+}/options/enum.ValidationAction.html>`__ for possible ``validation_action`` values
+
+To learn more about any other methods or types referenced in this
+guide, see the following documentation:
+
+- `create_collection() <{+api+}/struct.Database.html#method.create_collection>`__
+- `CreateCollectionOptions <{+api+}/options/struct.CreateCollectionOptions.html>`__
+- `validator <{+api+}/options/struct.CreateCollectionOptions.html#structfield.validator>`__

source/includes/fundamentals-sections.rst

@@ -2,12 +2,9 @@ Learn how to perform the following tasks using the {+driver-short+} in the
 Fundamentals section:
 
 - :ref:`Connect to MongoDB <rust-connection>`
-- :ref:`Specify the {+stable-api+} Version <rust-stable-api>`
-- :ref:`Authenticate to MongoDB <rust-authentication>`
 - :ref:`Read from and Write to MongoDB <rust-crud>`
-- :ref:`Manage Databases and Collections <rust-db-coll>`
+- :ref:`Implement Schema Validation <rust-schema-validation>`
 - :ref:`Perform Aggregations <rust-aggregation>`
-- :ref:`Record Driver Events <rust-tracing-logging>`
 - :ref:`Run A Database Command <rust-run-command>`
 
 ..
@@ -18,6 +15,7 @@ Fundamentals section:
   - :ref:`Convert Data to and from BSON <rust-bson>`
   - :ref:`Construct Indexes <rust-indexes>`
   - :ref:`Specify Collations to Order Results <rust-collations>`
+  - :ref:`Record Log Messages <rust-logging>`
   - :ref:`Monitor Driver Events <rust-monitoring>`
   - :ref:`Store and Retrieve Large Files by Using GridFS <rust-gridfs>`
   - :ref:`Use a Time Series Collection <rust-time-series>`

source/includes/fundamentals/code-snippets/schema-validation.rs

@@ -0,0 +1,35 @@
+use bson::{ Document };
+use mongodb::{ bson::doc, options::{ CollectionOptions, WriteConcern }, Client, Collection };
+use std::env;
+
+#[tokio::main]
+async fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+    let client = Client::with_uri_str(uri).await?;
+
+    let db: mongodb::Database = client.database("test_db");
+
+    // begin-schema-validation
+    let validator =
+        doc! {
+            "$jsonSchema": doc! {
+               "bsonType": "object",
+               "title": "Answer Value Validation",
+               "properties": doc! {
+                  "answer": doc! {
+                     "enum": vec! [ "yes", "no" ],
+                  }
+               }
+            }
+        };
+    let validation_opts = CreateCollectionOptions::builder()
+        .validator(validator)
+        .validation_action(Some(ValidationAction::Error))
+        .validation_level(Some(ValidationLevel::Moderate))
+        .build();
+
+    db.create_collection("survey_answers", validation_opts).await?;
+    // end-schema-validation
+
+    Ok(())
+}