DOCSP-50472: schema validation #3400

rustagir · 2025-06-05T20:20:05Z

https://jira.mongodb.org/browse/DOCSP-50472

Adds documentation for the jsonSchema() method.

Staging: https://deploy-preview-193--docs-laravel.netlify.app/eloquent-models/schema-builder/#implement-schema-validation

Checklist

Add tests and ensure they pass

…aravel-mongodb into DOCSP-50472-jsonSchema-method

mongoKart

some small things then LGTM

mongoKart · 2025-06-05T21:33:14Z

docs/eloquent-models/schema-builder.txt

+- ``Schema::create()``: When creating a new collection
+- ``Schema::table()``: When updating collection properties


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?

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.

mongoKart · 2025-06-05T21:34:20Z

docs/eloquent-models/schema-builder.txt

+- ``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


that/which

Suggested change

those write operations which follow the validation rules. Use schema

those write operations that follow the validation rules. Use schema

mongoKart · 2025-06-05T21:37:01Z

docs/eloquent-models/schema-builder.txt

+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.


S: i wonder if the connection between these two sentences would be clearer if you switched them. something like:

Suggested change

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 allows you to run only

those write operations which follow the validation rules.

makes sense

mongoKart · 2025-06-05T22:27:18Z

docs/eloquent-models/schema-builder.txt

+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 can include the following fields:


S: break up paragraphs differently. could also then remove first 'JSON'

Suggested change

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 can include the following fields:

Before creating a collection with schema validation rules, you must

define the schema.

A 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:

Removed this paragraph per PV suggestion

mongoKart · 2025-06-05T22:27:53Z

docs/eloquent-models/schema-builder.txt

+- ``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.


I: no periods

Suggested change

- ``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.

- ``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

removed this text

mongoKart · 2025-06-05T22:28:57Z

docs/eloquent-models/schema-builder.txt

+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


S:

Suggested change

contain the ``license_number`` field with an integer value between

contain the ``license_number`` field, and the field must have an integer value between

changed to a list

paulinevos · 2025-06-06T12:47:15Z

docs/eloquent-models/schema-builder.txt

+
+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``


$jsonSchema doesn't need to be included in the schema argument (see the example). Since the method is Blueprint::jsonSchema, the '$jsonSchema' operation is already implied.

So this documentation may be valid for MongoDB server but not for Laravel usage

Oh also! Since this is PHP, the schema argument is not an object, but an associative array.

paulinevos · 2025-06-06T12:50:37Z

docs/eloquent-models/schema-builder.txt

+this object must include a ``$jsonSchema`` object. The ``$jsonSchema``
+object can include the following fields:
+
+- ``title``: Sets an optional title for the schema.


Should we actually include this documentation? Seems to me the $jsonSchema operation is covered by the Mongo server docs. The Laravel ORM passes the schema through as is. I think specifying allowed fields here puts us in a situation of having to update this documentation when Mongo server specs change, when the user could just use the Mongo server docs as the single source of truth for jsonSchema usage.

That makes sense - I'll cut out some of this text and apply the suggestions from your prev comment.

paulinevos

Great! 🙏

DOCSP-50472: schema validation

1c45cb2

github-actions bot added the docs label Jun 5, 2025

rustagir and others added 4 commits June 5, 2025 20:20

apply phpcbf formatting

aa5e8cf

small wording fix

a6e72f5

Merge branch 'DOCSP-50472-jsonSchema-method' of github.com:rustagir/l…

737a009

…aravel-mongodb into DOCSP-50472-jsonSchema-method

fixes

24152bb

rustagir marked this pull request as ready for review June 5, 2025 20:30

rustagir requested a review from a team as a code owner June 5, 2025 20:30

rustagir requested a review from lindseymoore June 5, 2025 20:30

log error

1073888

rustagir requested a review from paulinevos June 5, 2025 20:36

rustagir added 2 commits June 5, 2025 16:38

fix int type

ea1d3a6

wip

84e8c85

mongoKart approved these changes Jun 5, 2025

View reviewed changes

paulinevos requested changes Jun 6, 2025

View reviewed changes

PV tech review 1

e425c9a

rustagir requested a review from paulinevos June 6, 2025 13:51

paulinevos approved these changes Jun 6, 2025

View reviewed changes

norareidy approved these changes Jun 6, 2025

View reviewed changes

rustagir merged commit 5fe1f5d into mongodb:5.x Jun 6, 2025
71 checks passed

		- ``Schema::create()``: When creating a new collection
		- ``Schema::table()``: When updating collection properties

	those write operations which follow the validation rules. Use schema
	those write operations that follow the validation rules. Use schema

	contain the ``license_number`` field with an integer value between
	contain the ``license_number`` field, and the field must have an integer value between

DOCSP-50472: schema validation #3400

DOCSP-50472: schema validation #3400

Uh oh!

Conversation

rustagir commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

mongoKart left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paulinevos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rustagir commented Jun 5, 2025 •

edited

Loading