From 1c45cb2a275de280068ee9e03f048c5cf7c2dba9 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:19:19 -0400
Subject: [PATCH 1/8] DOCSP-50472: schema validation

---
 docs/eloquent-models/schema-builder.txt       | 76 ++++++++++++++++---
 .../schema-builder/flights_migration.php      | 20 +++++
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt
index 3cdec0f03..e63dbc312 100644
--- a/docs/eloquent-models/schema-builder.txt
+++ b/docs/eloquent-models/schema-builder.txt
@@ -21,8 +21,9 @@ Overview
 --------
 
 Laravel provides a **facade** to access the schema builder class ``Schema``,
-which lets you create and modify tables. Facades are static interfaces to
-classes that make the syntax more concise and improve testability.
+which lets you create and modify tables, or collections in MongoDB.
+Facades are static interfaces to classes that make the syntax more
+concise and improve testability.
 
 The {+odm-short+} supports a subset of the index and collection management methods
 in the Laravel ``Schema`` facade.
@@ -33,16 +34,10 @@ in the Laravel documentation.
 The following sections describe the Laravel schema builder features available
 in the {+odm-short+} and show examples of how to use them:
 
-- :ref:`<laravel-eloquent-migrations>`
-- :ref:`<laravel-eloquent-collection-exists>`
-- :ref:`<laravel-eloquent-indexes>`
-
-.. note::
-
-   The {+odm-short+} supports managing indexes and collections, but
-   excludes support for MongoDB JSON schemas for data validation. To learn
-   more about JSON schema validation, see :manual:`Schema Validation </core/schema-validation/>`
-   in the {+server-docs-name+}.
+- :ref:`laravel-eloquent-migrations`
+- :ref:`laravel-eloquent-schema-validation`
+- :ref:`laravel-eloquent-collection-exists`
+- :ref:`laravel-eloquent-indexes`
 
 .. _laravel-eloquent-migrations:
 
@@ -117,6 +112,63 @@ To learn more about Laravel migrations, see
 `Database: Migrations <https://laravel.com/docs/{+laravel-docs-version+}/migrations>`__
 in the Laravel documentation.
 
+.. _laravel-eloquent-schema-validation:
+
+Implement Schema Validation
+---------------------------
+
+You can use the ``jsonSchema()`` method to implement **:manual:`schema
+validation </core/schema-validation/>`** when using the following schema
+builder methods:
+
+- ``Schema::create()``: When creating a new collection.
+- ``Schema::table()``: When updating collection properties.
+
+After you implement schema validation, the server allows you to run only
+those write operations which follow the validation rules. Use schema
+validation to restrict data types and value ranges of document fields in
+a specified collection.
+
+Before creating a collection with schema validation rules, you must
+define a JSON schema.
+
+The 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-docs-name+}.
+
+You can optionally pass the following parameters to ``jsonSchema()``:
+
+- ``validationLevel``: Sets the level of validation enforcement.
+  Accepted values are ``"strict"`` and ``"moderate"``.
+- ``validationAction``: Specifies the action to take when invalid
+  operations are attempted. Accepted values are ``"error"`` and
+  ``"warn"``.
+
+This example demonstrates how to pass a JSON schema to the
+``jsonSchema()`` method when creating a collection. The schema
+validation specifies that documents in the ``pilots`` collection must
+contain the ``license_number`` field with an integer value between
+``1000`` and ``9999``.
+
+.. literalinclude:: /includes/schema-builder/flights_migration.php
+   :language: php
+   :dedent:
+   :start-after: begin-json-schema
+   :end-before: end-json-schema
+
+If you attempt to insert a document into the ``pilots`` collection that
+violates the schema validation rule, {+odm-long+} returns a
+:php:`mongodb-driver-exception-bulkwriteexception` because the
+validation level is set to ``"error"``.
+
 .. _laravel-eloquent-collection-exists:
 
 Check Whether a Collection Exists
diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php
index 861c339ef..0a25c102a 100644
--- a/docs/includes/schema-builder/flights_migration.php
+++ b/docs/includes/schema-builder/flights_migration.php
@@ -19,6 +19,26 @@ public function up(): void
             $collection->unique('mission_id', options: ['name' => 'unique_mission_id_idx']);
         });
         // end create index
+
+        // begin-json-schema
+        Schema::create('pilots', function (Blueprint $collection) {
+            $collection->jsonSchema(
+                schema: [
+                    'bsonType' => 'object',
+                    'required' => ['license_number'],
+                    'properties' => [
+                        'license_number' => [
+                            'bsonType' => 'integer',
+                            'minimum' => 1000,
+                            'maximum' => 9999,
+                            'description' => 'requires the license_number field with an int value 1000-9999',
+                        ]
+                    ]
+                ],
+                validationAction: 'error'
+            );
+        });
+        // end-json-schema
     }
 
     public function down(): void

From aa5e8cf5c31211606a847b3e18a67675b9b3d501 Mon Sep 17 00:00:00 2001
From: rustagir <85902999+rustagir@users.noreply.github.com>
Date: Thu, 5 Jun 2025 20:20:40 +0000
Subject: [PATCH 2/8] apply phpcbf formatting

---
 docs/includes/schema-builder/flights_migration.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php
index 0a25c102a..04bb50618 100644
--- a/docs/includes/schema-builder/flights_migration.php
+++ b/docs/includes/schema-builder/flights_migration.php
@@ -32,10 +32,10 @@ public function up(): void
                             'minimum' => 1000,
                             'maximum' => 9999,
                             'description' => 'requires the license_number field with an int value 1000-9999',
-                        ]
-                    ]
+                        ],
+                    ],
                 ],
-                validationAction: 'error'
+                validationAction: 'error',
             );
         });
         // end-json-schema

From a6e72f592222a26cef4cbd55bbe77cc212b2e83e Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:26:43 -0400
Subject: [PATCH 3/8] small wording fix

---
 docs/eloquent-models/schema-builder.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt
index e63dbc312..dae27c7b6 100644
--- a/docs/eloquent-models/schema-builder.txt
+++ b/docs/eloquent-models/schema-builder.txt
@@ -167,7 +167,7 @@ contain the ``license_number`` field with an integer value between
 If you attempt to insert a document into the ``pilots`` collection that
 violates the schema validation rule, {+odm-long+} returns a
 :php:`mongodb-driver-exception-bulkwriteexception` because the
-validation level is set to ``"error"``.
+validation action is set to ``"error"``.
 
 .. _laravel-eloquent-collection-exists:
 

From 24152bb5c290f34241e51de0660e8bb66368c799 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:30:12 -0400
Subject: [PATCH 4/8] fixes

---
 docs/eloquent-models/schema-builder.txt            | 12 ++++++------
 docs/includes/schema-builder/flights_migration.php |  1 -
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt
index dae27c7b6..681605251 100644
--- a/docs/eloquent-models/schema-builder.txt
+++ b/docs/eloquent-models/schema-builder.txt
@@ -117,12 +117,12 @@ in the Laravel documentation.
 Implement Schema Validation
 ---------------------------
 
-You can use the ``jsonSchema()`` method to implement **:manual:`schema
-validation </core/schema-validation/>`** when using the following schema
+You can use the ``jsonSchema()`` method to implement :manual:`schema
+validation </core/schema-validation/>` when using the following schema
 builder methods:
 
-- ``Schema::create()``: When creating a new collection.
-- ``Schema::table()``: When updating collection properties.
+- ``Schema::create()``: When creating a new collection
+- ``Schema::table()``: When updating collection properties
 
 After you implement schema validation, the server allows you to run only
 those write operations which follow the validation rules. Use schema
@@ -166,8 +166,8 @@ contain the ``license_number`` field with an integer value between
 
 If you attempt to insert a document into the ``pilots`` collection that
 violates the schema validation rule, {+odm-long+} returns a
-:php:`mongodb-driver-exception-bulkwriteexception` because the
-validation action is set to ``"error"``.
+:php:`BulkWriteException <mongodb-driver-exception-bulkwriteexception>`
+because the validation action is set to ``"error"``.
 
 .. _laravel-eloquent-collection-exists:
 
diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php
index 04bb50618..29b2054d6 100644
--- a/docs/includes/schema-builder/flights_migration.php
+++ b/docs/includes/schema-builder/flights_migration.php
@@ -31,7 +31,6 @@ public function up(): void
                             'bsonType' => 'integer',
                             'minimum' => 1000,
                             'maximum' => 9999,
-                            'description' => 'requires the license_number field with an int value 1000-9999',
                         ],
                     ],
                 ],

From 10738889df39864881b9d162791b857ab5289be6 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:34:39 -0400
Subject: [PATCH 5/8] log error

---
 docs/quick-start/backend-service-tutorial.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/quick-start/backend-service-tutorial.txt b/docs/quick-start/backend-service-tutorial.txt
index 9236c698a..7ecdf8cf8 100644
--- a/docs/quick-start/backend-service-tutorial.txt
+++ b/docs/quick-start/backend-service-tutorial.txt
@@ -1,8 +1,8 @@
 .. _laravel-tutorial-backend-service:
 
-==========================================================
+===========================================================
 Tutorial: Build a Back End Service by Using {+odm-long+}
-========================================================== 
+===========================================================
 
 .. facet::
    :name: genre

From ea1d3a6c2197573f0e29b6e109fb7592807a2dd8 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:38:00 -0400
Subject: [PATCH 6/8] fix int type

---
 docs/includes/schema-builder/flights_migration.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/includes/schema-builder/flights_migration.php b/docs/includes/schema-builder/flights_migration.php
index 29b2054d6..4f776f260 100644
--- a/docs/includes/schema-builder/flights_migration.php
+++ b/docs/includes/schema-builder/flights_migration.php
@@ -28,7 +28,7 @@ public function up(): void
                     'required' => ['license_number'],
                     'properties' => [
                         'license_number' => [
-                            'bsonType' => 'integer',
+                            'bsonType' => 'int',
                             'minimum' => 1000,
                             'maximum' => 9999,
                         ],

From 84e8c85818c10e9063f23cf9058f715fe697f69b Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 5 Jun 2025 16:44:24 -0400
Subject: [PATCH 7/8] wip

---
 docs/eloquent-models/schema-builder.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt
index 681605251..d5851c145 100644
--- a/docs/eloquent-models/schema-builder.txt
+++ b/docs/eloquent-models/schema-builder.txt
@@ -135,21 +135,21 @@ define a JSON schema.
 The 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:
+object can include the following fields:
 
-- ``title``: Sets an optional description for the schema.
+- ``title``: Sets an optional title 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
+To view a full list of JSON schema object fields, see :manual:`JSON Schema
 </reference/operator/query/jsonSchema/#json-schema>` in the {+server-docs-name+}.
 
 You can optionally pass the following parameters to ``jsonSchema()``:
 
 - ``validationLevel``: Sets the level of validation enforcement.
-  Accepted values are ``"strict"`` and ``"moderate"``.
+  Accepted values are ``"strict"`` (default) and ``"moderate"``.
 - ``validationAction``: Specifies the action to take when invalid
-  operations are attempted. Accepted values are ``"error"`` and
+  operations are attempted. Accepted values are ``"error"`` (default) and
   ``"warn"``.
 
 This example demonstrates how to pass a JSON schema to the

From e425c9ae0a0fd0b0b3ce50f1822fe4aed13f7ebb Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 6 Jun 2025 09:50:23 -0400
Subject: [PATCH 8/8] PV tech review 1

---
 docs/eloquent-models/schema-builder.txt | 47 ++++++++++++-------------
 1 file changed, 22 insertions(+), 25 deletions(-)

diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt
index d5851c145..e9c1dff17 100644
--- a/docs/eloquent-models/schema-builder.txt
+++ b/docs/eloquent-models/schema-builder.txt
@@ -124,39 +124,37 @@ builder methods:
 - ``Schema::create()``: When creating a new collection
 - ``Schema::table()``: When updating collection properties
 
-After you implement schema validation, the server allows you to run only
-those write operations which follow the validation rules. Use schema
-validation to restrict data types and value ranges of document fields in
-a specified collection.
+You can use schema validation to restrict data types and value ranges of
+document fields in a specified collection. After you implement schema
+validation, the server restricts write operations that don't follow the
+validation rules.
 
-Before creating a collection with schema validation rules, you must
-define a JSON schema.
+You can pass the following parameters to ``jsonSchema()``:
 
-The 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 can include the following fields:
-
-- ``title``: Sets an optional title for the schema.
-- ``required``: Specifies a list of required fields for each document in your collection.
-- ``properties``: Sets property requirements for individual fields.
-
-To view a full list of JSON schema object fields, see :manual:`JSON Schema
-</reference/operator/query/jsonSchema/#json-schema>` in the {+server-docs-name+}.
-
-You can optionally pass the following parameters to ``jsonSchema()``:
+- ``schema``: Array that specifies the validation rules for the
+  collection. To learn more about constructing a schema, see
+  the :manual:`$jsonSchema </reference/operator/query/jsonSchema/>`
+  reference in the {+server-docs-name+}.
 
 - ``validationLevel``: Sets the level of validation enforcement.
   Accepted values are ``"strict"`` (default) and ``"moderate"``.
+
 - ``validationAction``: Specifies the action to take when invalid
   operations are attempted. Accepted values are ``"error"`` (default) and
   ``"warn"``.
 
-This example demonstrates how to pass a JSON schema to the
+This example demonstrates how to specify a schema in the
 ``jsonSchema()`` method when creating a collection. The schema
-validation specifies that documents in the ``pilots`` collection must
-contain the ``license_number`` field with an integer value between
-``1000`` and ``9999``.
+validation has the following specifications:
+
+- Documents in the ``pilots`` collection must
+  contain the ``license_number`` field.
+
+- The ``license_number`` field must have an integer value between
+  ``1000`` and ``9999``.
+
+- If you attempt to perform invalid write operations, the server raises
+  an error.
 
 .. literalinclude:: /includes/schema-builder/flights_migration.php
    :language: php
@@ -166,8 +164,7 @@ contain the ``license_number`` field with an integer value between
 
 If you attempt to insert a document into the ``pilots`` collection that
 violates the schema validation rule, {+odm-long+} returns a
-:php:`BulkWriteException <mongodb-driver-exception-bulkwriteexception>`
-because the validation action is set to ``"error"``.
+:php:`BulkWriteException <mongodb-driver-exception-bulkwriteexception>`.
 
 .. _laravel-eloquent-collection-exists: