Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

DOCSP-50472: schema validation #3400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rustagir merged 9 commits into mongodb:5.x from rustagir:DOCSP-50472-jsonSchema-method
Jun 6, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 61 additions & 12 deletions docs/eloquent-models/schema-builder.txt
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:

Expand Down Expand Up @@ -117,6 +112,60 @@ 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
Comment on lines +124 to +125
Copy link
Contributor

@mongoKart mongoKart Jun 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: can you only implement schema validation when using these methods for these specific purposes? or is the info after the colons just a reminder of the method's purpose?

Copy link
Collaborator

@paulinevos paulinevos Jun 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are the only two methods in Laravel's Schema that accept a callback to alter columns, so you can only implement schema validation on either creating a collection or updating it.

rustagir reacted with thumbs up emoji

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.

You can 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 specify a schema in the
``jsonSchema()`` method when creating a collection. The schema
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
: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:`BulkWriteException <mongodb-driver-exception-bulkwriteexception>`.

.. _laravel-eloquent-collection-exists:

Check Whether a Collection Exists
Expand Down
19 changes: 19 additions & 0 deletions docs/includes/schema-builder/flights_migration.php
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,25 @@ 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' => 'int',
'minimum' => 1000,
'maximum' => 9999,
],
],
],
validationAction: 'error',
);
});
// end-json-schema
}

public function down(): void
Expand Down
4 changes: 2 additions & 2 deletions docs/quick-start/backend-service-tutorial.txt
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
.. _laravel-tutorial-backend-service:

==========================================================
===========================================================
Tutorial: Build a Back End Service by Using {+odm-long+}
==========================================================
===========================================================

.. facet::
:name: genre
Expand Down
Loading

AltStyle によって変換されたページ (->オリジナル) /