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

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

Copy link

Contributor

@rustagir rustagir commented Jun 5, 2025 •

edited

Loading

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


 DOCSP-50472: schema validation

1c45cb2

@github-actions github-actions bot added the docs label

Jun 5, 2025

rustagir and others added 4 commits

June 5, 2025 20:20

@rustagir @github-actions


 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 rustagir marked this pull request as ready for review

June 5, 2025 20:30

@rustagir rustagir requested a review from a team as a code owner

June 5, 2025 20:30

@rustagir rustagir requested a review from lindseymoore

June 5, 2025 20:30


 log error

@rustagir 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

mongoKart approved these changes

Jun 5, 2025

Copy link

Contributor

@mongoKart mongoKart left a comment

Choose a reason for hiding this comment

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

some small things then LGTM

docs/eloquent-models/schema-builder.txt

Comment on lines +124 to +125

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

- ``Schema::table()``: When updating collection properties

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.

docs/eloquent-models/schema-builder.txt Outdated

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

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.

that/which

Suggested change

those write operations which follow the validation rules. Use schema

those write operations that follow the validation rules. Use schema

docs/eloquent-models/schema-builder.txt Outdated

Comment on lines 127 to 130

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.

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.

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.

Copy link

Contributor Author

@rustagir rustagir Jun 6, 2025

Choose a reason for hiding this comment

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

makes sense

docs/eloquent-models/schema-builder.txt Outdated

Comment on lines 132 to 138

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:

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.

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:

Copy link

Contributor Author

@rustagir rustagir Jun 6, 2025

Choose a reason for hiding this comment

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

Removed this paragraph per PV suggestion

docs/eloquent-models/schema-builder.txt Outdated

Comment on lines 140 to 142

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

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.

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

Copy link

Contributor Author

@rustagir rustagir Jun 6, 2025

Choose a reason for hiding this comment

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

removed this text

docs/eloquent-models/schema-builder.txt Outdated

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

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.

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

Copy link

Contributor Author

@rustagir rustagir Jun 6, 2025

Choose a reason for hiding this comment

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

changed to a list

paulinevos

paulinevos requested changes

docs/eloquent-models/schema-builder.txt Outdated

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

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.

$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

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.

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

docs/eloquent-models/schema-builder.txt Outdated

this object must include a ``$jsonSchema`` object. The ``$jsonSchema``

object can include the following fields:

- ``title``: Sets an optional title for the schema.

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.

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.

Copy link

Contributor Author

@rustagir rustagir Jun 6, 2025

Choose a reason for hiding this comment

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

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


 PV tech review 1

e425c9a

@rustagir rustagir requested a review from paulinevos

June 6, 2025 13:51

paulinevos

paulinevos approved these changes

Copy link

Collaborator

@paulinevos paulinevos left a comment

Choose a reason for hiding this comment

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

Great! 🙏

norareidy

norareidy approved these changes

@rustagir rustagir merged commit 5fe1f5d into mongodb:5.x