DOCSP-34316 Update Role Example Descriptions

mongodb · Nov 16, 2023 · 8e3e818 · 8e3e818
1 parent 49c3e0b
commit 8e3e818
Show file tree

Hide file tree

Showing 11 changed files with 25 additions and 21 deletions.
diff --git a/source/images/role-template-can-write-some-fields.png b/source/images/role-template-can-write-some-fields.png
diff --git a/source/images/role-template-cannot-insert-new-docs.png b/source/images/role-template-cannot-insert-new-docs.png
diff --git a/source/images/role-template-cannot-write-some-fields.png b/source/images/role-template-cannot-write-some-fields.png
diff --git a/source/images/role-template-cannot-write-to-specific-fields.png b/source/images/role-template-cannot-write-to-specific-fields.png
diff --git a/source/images/role-template-no-insert.png b/source/images/role-template-no-insert.png
diff --git a/source/images/role-template-read-all-data.png b/source/images/role-template-read-all-data.png
diff --git a/source/images/role-template-read-all.png b/source/images/role-template-read-all.png
diff --git a/source/images/role-template-read-and-write-all.png b/source/images/role-template-read-and-write-all.png
diff --git a/source/images/role-template-read-write-all-data.png b/source/images/role-template-read-write-all-data.png
diff --git a/source/images/role-template-write-specific-fields.png b/source/images/role-template-write-specific-fields.png
diff --git a/source/rules/examples.txt b/source/rules/examples.txt
@@ -150,24 +150,26 @@ The Role Can Read All Fields but Cannot Write
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To allow a role to read any field, set the document-level ``read`` field
-to ``true``.
+to ``true`` and ``write`` field to ``false``.
 
 .. list-table::
    :widths: 50 50
 
-   * - .. figure:: /images/role-template-read-all-data.png
+   * - .. figure:: /images/role-read-all.png
           :alt: A role with permission to read all document fields
           :width: 350px
 
      - .. code-block:: json
-          :emphasize-lines: 6
+          :emphasize-lines: 7-8
 
           {
             "name": "<Role Name>",
-            "apply_when": <JSON Expression>,
+            "apply_when": {<JSON Expression>},
+            "document_filters": {<JSON Expression>},
             "insert": <boolean>,
             "delete": <boolean>,
             "read": true,
+            "write": false
           }
 
 The Role Can Read & Write All Fields
@@ -180,16 +182,17 @@ permission, so the role will be able to read all fields.
 .. list-table::
    :widths: 50 50
 
-   * - .. figure:: /images/role-template-read-write-all-data.png
+   * - .. figure:: /images/role-read-and-write-all.png
           :alt: A role with permission to read and write all document fields
           :width: 350px
 
      - .. code-block:: json
-          :emphasize-lines: 6
+          :emphasize-lines: 7
 
           {
             "name": "<Role Name>",
-            "apply_when": <JSON Expression>,
+            "apply_when": {<JSON Expression>},
+            "document_filters": {<JSON Expression>},
             "insert": <boolean>,
             "delete": <boolean>,
             "write": true,
@@ -199,26 +202,28 @@ The Role Can Read All Fields & Write to Specific Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To allow a role to read all fields, set the document-level ``read``
-field to ``true``. To specify a field that the role can write to, set
+field to ``true`` and the ``write`` field to ``false``. To specify a field that the role can write to, set
 the ``write`` field to ``true`` in the field's configuration document,
 which is embedded in the ``fields`` document.
 
 .. list-table::
    :widths: 50 50
 
-   * - .. figure:: /images/role-template-write-specific-fields.png
+   * - .. figure:: /images/role-template-can-write-some-fields.png
           :alt: A role with permission to write to specific fields
           :width: 350px
 
      - .. code-block:: json
-          :emphasize-lines: 6, 8
+          :emphasize-lines: 7, 8, 10
 
           {
             "name": "<Role Name>",
-            "apply_when": <JSON Expression>,
+            "apply_when": {<JSON Expression>},
+            "document_filters": {<JSON Expression>},
             "insert": <boolean>,
             "delete": <boolean>,
             "read": true,
+            "write": false,
             "fields": {
               "<Field Name>": { "write": true },
               ...
@@ -238,20 +243,17 @@ To prevent the role from inserting new documents, set the document-level
 .. list-table::
    :widths: 50 50
 
-   * - .. figure:: /images/role-template-no-insert.png
+   * - .. figure:: /images/role-template-cannot-write-to-specific-fields.png
           :alt: A role that lacks permission to insert new documents
           :width: 350px
-
-       .. figure:: /images/role-template-read-write-all-data.png
-          :alt: A role with permission to read and write all document fields
-          :width: 350px
 
      - .. code-block:: json
-          :emphasize-lines: 4, 6
+          :emphasize-lines: 5, 7
 
           {
             "name": "<Role Name>",
-            "apply_when": <JSON Expression>,
+            "apply_when": {<JSON Expression>},
+            "document_filters": {<JSON Expression>},
             "insert": false,
             "delete": <boolean>,
             "write": true,
@@ -263,20 +265,22 @@ The Role Cannot Write to Specific Fields
 To allow a role to write to any field except for those you specify, set
 the corresponding field-level ``write`` fields to ``false`` in the
 ``fields`` document and set the ``additional_fields.write`` field to
-``true``.
+``true``. Document-level writes require read
+permission, so the role will be able to read all additional fields.
 
 .. list-table::
    :widths: 50 50
 
-   * - .. figure:: /images/role-template-cannot-write-some-fields.png
+   * - .. figure:: /images/role-template-cannot-write-to-specific-fields.png
           :alt: A role with permission to write to some but not all fields
           :width: 350px
 
      - .. code-block:: json
 
           {
             "name": "<Role Name>",
-            "apply_when": <JSON Expression>,
+            "apply_when": {<JSON Expression>},
+            "document_filters": {<JSON Expression>},
             "insert": <boolean>,
             "delete": <boolean>,
             "read": true,