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: