docs: add defined schema docs #863

Moumouls · 2022-02-20T12:23:24Z

Add defined schema docs.

Moumouls · 2022-02-20T12:25:18Z

@sadortun if you want to take a look, feel to suggest some commit changes from github UI 🙂

mtrezza · 2022-02-20T17:28:04Z

_includes/defined-schema/class-level-permissions.md

+- `delete`: Delete permission
+- `protectedFields`: Control get permission at field level
+
+You can set each CLP field with options to add a first strong security layer. This security layer will be applied on the Parse Class and all Parse Objects into this class.


"into this class"? Do you mean sub classes?

mtrezza · 2022-02-20T17:29:15Z

_includes/defined-schema/class-level-permissions.md

+
+## CLP Protected Fields Key
+
+This CLP key is powerful and need some additional explanation.


I think this line can be removed, it doesn't seem to provide any relevant info. Maybe instead a sentence about what this is (used for).

mtrezza · 2022-02-20T17:30:34Z

_includes/defined-schema/class-level-permissions.md

+}
+```
+
+Listed keys under `*` will be protected from all users. Don't worry by default, `authData`, `emailVerified`, `password` are protected.


Remove "don't worry"

mtrezza · 2022-02-20T17:31:17Z

_includes/defined-schema/class-level-permissions.md

+```
+
+Listed keys under `*` will be protected from all users. Don't worry by default, `authData`, `emailVerified`, `password` are protected.
+But here for example we protect `username` from all users. So user A, even authenticated will not be able to get the `username` of a user B.


Where is "here"? There is an example before and one after.

mtrezza · 2022-02-20T17:33:02Z

_includes/defined-schema/class-level-permissions.md

+```
+
+Listed keys under `*` will be protected from all users. Don't worry by default, `authData`, `emailVerified`, `password` are protected.
+But here for example we protect `username` from all users. So user A, even authenticated will not be able to get the `username` of a user B.


The references "user A", "user B" seem to not be used anywhere else? If so, just simplify this to something like "a user cannot ... of other users".

mtrezza · 2022-02-20T17:54:30Z

_includes/defined-schema/options.md

+
+## strict
+
+You can set the `strict` option to `true` if you want parse-server to delete removed classes from your schemas from your database. Data stored in removed classes will be lost.


"Parse Server"

Could you rephrase "from your schemas from your database", may be confusing

mtrezza · 2022-02-20T17:56:54Z

_includes/defined-schema/options.md

+
+You can set the `strict` option to `true` if you want parse-server to delete removed classes from your schemas from your database. Data stored in removed classes will be lost.
+
+`strict` is default to `false`. If you often change your schemas be aware that you can have some stale classes in your database. You will need to delete these classes manually.


"By default strict is false.

"You can have stale..." sounds like it's permissible. I think you want to say that the stale classes are unwanted and may remain?

mtrezza · 2022-02-20T17:58:17Z

_includes/defined-schema/options.md

+
+## deleteExtraFields
+
+You can set the `deleteExtraFields` option to `true` if you parse-server to delete removed a class field from your database. Data stored in the removed field will be lost.


"if you want Parse Server to..."

"Delete remove" - a typo?

mtrezza · 2022-02-20T17:59:50Z

_includes/defined-schema/options.md

+
+You can set the `deleteExtraFields` option to `true` if you parse-server to delete removed a class field from your database. Data stored in the removed field will be lost.
+
+`deleteExtraFields` is default to `false`. Be aware that some stale fields could exists in your database. You will need to delete these fields manually.


Same here rephrasing

mtrezza · 2022-02-20T18:01:01Z

_includes/defined-schema/options.md

+
+## beforeMigration
+
+A function called before parse-server performs schema updates based on the `definitions` option


Always use "Parse Server" when you refer to the product, don't use "parse-server" unless you are referring to the repository.

sadortun · 2022-02-21T22:08:14Z

_includes/defined-schema/class-level-permissions.md

+
+Note: If you update CLP you do not need to update Parse Objects. CLP is a security layer at Class Level not Object Level. For Object Level permission you can take a look to ALCs. You can use CLPs combined to ACLs to deeply secure your Parse Server.
+
+## CLP Key Options


I would suggest replacing globally key with either parameter or attribute depending on the context.

Currently parameter seems to be more generalized as config keys

https://docs.parseplatform.org/parse-server/guide/#usage

sadortun · 2022-02-21T22:13:29Z

_includes/defined-schema/getting-started.md

+    // and then create the field with the new type
+    recreateModifiedFields: true,
+    // If true, Parse will delete non defined fields on a class. (Core fields are never deleted)
+    deleteExtraFields: true,


Theses 2 parameters should be false by default in the example to avoir a user copy-pasting the example config have it's data deleted unintentionally.

Moumouls · 2022-03-05T09:37:11Z

@sadortun @mtrezza requested changes performed. Feel free to use the Github commit suggestion feature if you some new changes suggestions, then i can apply easily your changes :)

sadortun

Excellent!

Only thing could be to add some Bold/red font on dangerous options

sadortun · 2022-03-05T17:33:21Z

_includes/defined-schema/options.md

+
+You can set the `recreateModifiedFields` option to `true` if you want Parse Server to clean field data before Parse Server update the field type when you change the type of a field (ie: from `String` to `Number`). Data stored on the modified field will be lost.
+
+`recreateModifiedFields` is default to `false`. Be aware that if you do not perform some data migration, you can result with data type inconsistency on modified field.


Maybe adding some Bold for ?

Be aware that if you do not perform some data migration

Moumouls · 2022-03-18T10:26:21Z

@sadortun i added bold, @mtrezza since Parse V5 was released, what do you think about merging this one ?

mtrezza

General feedback: the texts are quite verbose. Try to condense essential information into few words. Try to use as few lines as possible, instead of many lines with only a few words per line, that makes it easier to read and uses less space. For example:

// Here your Parse Server is ready
// with schemas up to date

// Just a code example if you want to expose
// an endpoint when parse is fully initialized

can be condensed into

// Parse Server is ready with up-to-date schema

mtrezza · 2022-03-24T16:20:46Z

_includes/defined-schema/class-level-permissions.md

+- `role:MyRole`: If you have already created a Parse Role, you can use your created Parse Role (ie: `MyRole`) in CLP keys.
+- `requiresAuthentication`: If true an authenticated user will have the permission.
+- `*`: Everybody has the permission
+- `{}`: if you set the CLP key with `{}` like `create: {}` only calls with your Parse Server Master Key will have the permission


"`role:<roleName>`: If you are making use of Parse Roles you can set the permission based on a role."
...
"If you set the CLP key to `{}`" ... "calls with the Parse Server master key will"

mtrezza · 2022-03-24T16:23:19Z

_includes/defined-schema/class-level-permissions.md

+Available options for CLP parameters:
+
+- `role:MyRole`: If you have already created a Parse Role, you can use your created Parse Role (ie: `MyRole`) in CLP keys.
+- `requiresAuthentication`: If true an authenticated user will have the permission.


"If set to `true`, only authenticated users"

mtrezza · 2022-03-24T16:23:19Z

_includes/defined-schema/class-level-permissions.md

+Available options for CLP parameters:
+
+- `role:MyRole`: If you have already created a Parse Role, you can use your created Parse Role (ie: `MyRole`) in CLP keys.
+- `requiresAuthentication`: If true an authenticated user will have the permission.


"If set to `true`, only authenticated users"

mtrezza · 2022-03-24T16:24:08Z

_includes/defined-schema/class-level-permissions.md

+
+This CLP parameter allows you to restrict access to fields to specific Parse users.
+
+We will take the Parse User Class as example.


"as an example:"

mtrezza · 2022-03-24T16:24:08Z

_includes/defined-schema/class-level-permissions.md

+
+This CLP parameter allows you to restrict access to fields to specific Parse users.
+
+We will take the Parse User Class as example.


"as an example."

mtrezza · 2022-03-24T17:28:17Z

_includes/defined-schema/options.md

+
+`recreateModifiedFields` is default to `false`. **Be aware that if you do not perform some data migration, you can result with data type inconsistency on modified field.**
+
+On production a good practice could be to create a new field with your new type, and then create a Parse Cloud Job to migrate old field data to the new created field.


"Good practice would be to create a new field with a new type" ... "to the newly created field."

mtrezza · 2022-03-24T17:31:59Z

_includes/defined-schema/options.md

+
+## lockSchemas
+
+You can set the `lockSchemas` option to `true` if you want to to prevent any `Parse.Schema` manipulation outside of the Defined Schema feature. If this options is `true` any create/update/delete request to `Parse.Schema` will be denied. You will not be able to manipulate `indexes`, `classLevelPermissions`, `fields`.


"if you want to prevent any schema manipulation and to lock the schema as defined in the Parse Server configuration." ... "any create, update and delete request will be denied by the Parse Server API, even with the master key."

You can delete the following sentence "This option help to keep " as it does not provide any additional information.

mtrezza · 2022-03-24T17:31:59Z

_includes/defined-schema/options.md

+
+## lockSchemas
+
+You can set the `lockSchemas` option to `true` if you want to to prevent any `Parse.Schema` manipulation outside of the Defined Schema feature. If this options is `true` any create/update/delete request to `Parse.Schema` will be denied. You will not be able to manipulate `indexes`, `classLevelPermissions`, `fields`.


"if you want to prevent any schema manipulation and to lock the schema as defined in the Parse Server configuration."

mtrezza · 2022-03-24T17:35:59Z

_includes/defined-schema/options.md

+
+## beforeMigration
+
+A function called before parse-server performs schema updates based on the `definitions` option


mtrezza · 2022-03-24T17:35:59Z

_includes/defined-schema/options.md

+
+## beforeMigration
+
+A function called before parse-server performs schema updates based on the `definitions` option


stephannielsen · 2022-05-02T14:55:24Z

Maybe not the best place to ask but as there is no official documentation available yet:

Can we define on schema levels Array of Pointers of a specific class? This PR does not mention this and from some tests it seems that if you specify Array as type in the schema, anything is accepted as array content.
It would be nice if the documentation could include some examples on how to use beforeMigration and afterMigration hooks. I am not sure how I could leverage them to migrate data.

mtrezza · 2022-05-02T16:17:45Z

Thanks for the feedback to the docs, maybe @Moumouls can add this to the PR?
To your first point, the best place to ask is our community forum.

Moumouls · 2022-05-02T16:26:43Z

thanks, @stephannielsen for your feedback I'll quickly answer to your question. Parse is not currently able to type the content of Array. Anything could be stored in the Array. You can use the beforeSave Parse Cloud hook to prevent users saving anything other than the desired pointers.

If you use the GraphQL API. You can use the "inline fragment" graphql feature to automatically get data from the pointer array.

https://community.parseplatform.org/t/type-arrayresult-must-have-a-selection-of-subfields-error/847/2?u=moumouls

for example ... on MyPointerClass { id aField}

stephannielsen · 2022-05-02T19:16:35Z

Thanks @Moumouls and @mtrezza for your quick replies.

I already expected that Parse can't type array fields and that triggers would allow me to validate incoming data. Thanks for the quick confirmation.

RahulLanjewar93 · 2022-05-12T07:57:42Z

Hey, just had a quick question, since the documentation isn't updated yet. Can we have unique indexes according to the recent merge?

Thanks.

mtrezza · 2022-05-12T09:59:16Z

If anyone wants to pick up and finish this PR (see the review comments, just grammar and style corrections), please feel free to do so, so we can merge this chapter about defined schema into the docs. You will probably have to open a new PR, then we can close this one.

I have added a description to this PR and created issue #872 to track this.

Moumouls · 2022-11-14T23:38:41Z

@mtrezza any chance to update your comments using the commit suggestion feature ? then I'll be happy to apply all your suggestions 🚀

Moumouls · 2022-12-24T13:52:01Z

closing in favor of #912

feat: defined schema docs

b8bb023

Moumouls requested a review from mtrezza February 20, 2022 12:23

mtrezza requested changes Feb 20, 2022

View reviewed changes

sadortun reviewed Feb 21, 2022

View reviewed changes

fix: requested changes

2b651bb

Moumouls requested a review from mtrezza March 5, 2022 09:37

sadortun reviewed Mar 5, 2022

View reviewed changes

fix: add bold

938474c

Moumouls mentioned this pull request Mar 18, 2022

Add docs for Parse Server Schemas #844

Closed

mtrezza mentioned this pull request Mar 22, 2022

feat: add user-defined schema and migrations parse-community/parse-server#7418

Merged

6 tasks

mtrezza requested changes Mar 24, 2022

View reviewed changes

mtrezza changed the title ~~feat: defined schema docs~~ docs: defined schema docs May 12, 2022

mtrezza changed the title ~~docs: defined schema docs~~ docs: add defined schema docs May 12, 2022

epietrowicz mentioned this pull request Dec 16, 2022

Defined schemas updates #908

Closed

Moumouls closed this Dec 24, 2022


		## CLP Protected Fields Key

		This CLP key is powerful and need some additional explanation.


		## strict

		You can set the `strict` option to `true` if you want parse-server to delete removed classes from your schemas from your database. Data stored in removed classes will be lost.


		You can set the `strict` option to `true` if you want parse-server to delete removed classes from your schemas from your database. Data stored in removed classes will be lost.

		`strict` is default to `false`. If you often change your schemas be aware that you can have some stale classes in your database. You will need to delete these classes manually.


		## deleteExtraFields

		You can set the `deleteExtraFields` option to `true` if you parse-server to delete removed a class field from your database. Data stored in the removed field will be lost.


		You can set the `deleteExtraFields` option to `true` if you parse-server to delete removed a class field from your database. Data stored in the removed field will be lost.

		`deleteExtraFields` is default to `false`. Be aware that some stale fields could exists in your database. You will need to delete these fields manually.


		## beforeMigration

		A function called before parse-server performs schema updates based on the `definitions` option


		Note: If you update CLP you do not need to update Parse Objects. CLP is a security layer at Class Level not Object Level. For Object Level permission you can take a look to ALCs. You can use CLPs combined to ACLs to deeply secure your Parse Server.

		## CLP Key Options


		You can set the `recreateModifiedFields` option to `true` if you want Parse Server to clean field data before Parse Server update the field type when you change the type of a field (ie: from `String` to `Number`). Data stored on the modified field will be lost.

		`recreateModifiedFields` is default to `false`. Be aware that if you do not perform some data migration, you can result with data type inconsistency on modified field.


		This CLP parameter allows you to restrict access to fields to specific Parse users.

		We will take the Parse User Class as example.


		`recreateModifiedFields` is default to `false`. Be aware that if you do not perform some data migration, you can result with data type inconsistency on modified field.

		On production a good practice could be to create a new field with your new type, and then create a Parse Cloud Job to migrate old field data to the new created field.


		## lockSchemas

		You can set the `lockSchemas` option to `true` if you want to to prevent any `Parse.Schema` manipulation outside of the Defined Schema feature. If this options is `true` any create/update/delete request to `Parse.Schema` will be denied. You will not be able to manipulate `indexes`, `classLevelPermissions`, `fields`.

docs: add defined schema docs #863

docs: add defined schema docs #863

Conversation

Moumouls commented Feb 20, 2022 • edited by mtrezza Loading

Moumouls commented Feb 20, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Moumouls commented Mar 5, 2022

sadortun left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Moumouls commented Mar 18, 2022

mtrezza left a comment

Choose a reason for hiding this comment

mtrezza Mar 24, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stephannielsen commented May 2, 2022 • edited Loading

mtrezza commented May 2, 2022

Moumouls commented May 2, 2022 • edited Loading

stephannielsen commented May 2, 2022

RahulLanjewar93 commented May 12, 2022

mtrezza commented May 12, 2022 • edited Loading

Moumouls commented Nov 14, 2022

Moumouls commented Dec 24, 2022

Moumouls commented Feb 20, 2022 •

edited by mtrezza

Loading

Moumouls commented Feb 20, 2022 •

edited

Loading

mtrezza Mar 24, 2022 •

edited

Loading

stephannielsen commented May 2, 2022 •

edited

Loading

Moumouls commented May 2, 2022 •

edited

Loading

mtrezza commented May 12, 2022 •

edited

Loading