docs: add defined schema docs

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

@@ -0,0 +1,61 @@
+# Class Level Permissions
+
+Setting Class Level Permissions through Defined Schema is a good first step into security systems available on Parse Server.
+
+## CLP Parameters
+
+These CLP parameters are available:
+
+- `find`: Control search permissions
+- `get`: Control direct ID get permission
+- `count`: Control counting objects permission
+- `create`: Create permission
+- `update`: Update permission
+- `delete`: Delete permission
+- `protectedFields`: Control get permission at field level
+
+You can set each CLP parameter to add a first strong security layer. This security layer will be applied on the Parse Class and will cover all Parse Objects of the Parse Class.
+
+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 Parameter Options
+
+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.
+- `*`: 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
+
+## CLP Protected Fields Parameter
+
+This CLP parameter allows you to restrict access to fields to specific Parse users.
+
+We will take the Parse User Class as example.
+
+```js
+// className: '_User'
+{
+    protectedFields: {
+      "*": ["authData", "emailVerified", "password", "username"],
+    },
+}
+```
+
+Listed keys under `*` will be protected from all users. By default, `authData`, `emailVerified`, `password` are protected.
+But in the above example we protect `username` from all users. So a Parse User, even authenticated will not be able to get the `username` of a another Parse User.
+
+`protectedFields` could be also combined as in the following example.
+
+```js
+{
+    protectedFields: {
+      "*": ["authData", "emailVerified", "password", "username", "phone", "score"],
+      "role:Admin": ["password", "authData", "emailVerified"],
+      "role:VerifiedUser": ["password", "authData", "emailVerified", "score"],
+    },
+}
+```
+
+In the example above, a Parse User member of the Parse Role `Admin` will be able to get the `phone` and `score` of another Parse User. A Parse User member of the Parse Role `VerifiedUser` can only get `phone`.
+If a Parse User is member of `VerifiedUser` and `Admin`, he will have access to `phone` and `score`.

_includes/defined-schema/core-classes-fields.md

@@ -0,0 +1,108 @@
+# Core Classes/Fields
+
+Parse will never delete these fields on **ALL** classes if not provided in a class schema
+
+- `objectId`
+- `createdAt`
+- `updatedAt`
+- `ACL`
+
+Parse Server will never delete the following fields from any class, even if these fields are not defined in a class schema.
+
+- `_User`
+
+  - `username`
+  - `password`
+  - `email`
+  - `emailVerified`
+  - `authData`
+
+- `_Installation`
+
+  - `installationId`
+  - `deviceToken`
+  - `channels`
+  - `deviceType`
+  - `pushType`
+  - `GCMSenderId`
+  - `timeZone`
+  - `localeIdentifier`
+  - `badge`
+  - `appVersion`
+  - `appName`
+  - `appIdentifier`
+  - `parseVersion`
+
+- `_Role`
+
+  - `name`
+  - `users`
+  - `roles`
+
+- `_Session`
+
+  - `user`
+  - `installationId`
+  - `sessionToken`
+  - `expiresAt`
+  - `createdWith`
+
+- `_Product`
+
+  - `productIdentifier`
+  - `download`
+  - `downloadName`
+  - `icon`
+  - `order`
+  - `title`
+  - `subtitle`
+
+- `_PushStatus`
+
+  - `pushTime`
+  - `source`
+  - `query`
+  - `payload`
+  - `title`
+  - `expiry`
+  - `expiration_interval`
+  - `status`
+  - `numSent`
+  - `numFailed`
+  - `pushHash`
+  - `errorMessage`
+  - `sentPerType`
+  - `failedPerType`
+  - `sentPerUTCOffset`
+  - `failedPerUTCOffset`
+  - `count`
+
+- `_JobStatus`
+
+  - `jobName`
+  - `source`
+  - `status`
+  - `message`
+  - `params`
+  - `finishedAt`
+
+- `_JobSchedule`
+
+  - `jobName`
+  - `description`
+  - `params`
+  - `startAfter`
+  - `daysOfWeek`
+  - `timeOfDay`
+  - `lastRun`
+  - `repeatMinutes`
+
+- `_Audience`
+  - `objectId`
+  - `name`
+  - `query`
+  - `lastUsed`
+  - `timesUsed`
+- `_Idempotency`
+  - `reqId`
+  - `expire`

_includes/defined-schema/fields.md

@@ -0,0 +1,42 @@
+# Fields
+
+These field types are available on a Parse Schema.
+
+`required`: `boolean`, by default false. Force the field to be set on create and update.
+`defaultValue`: `any`, a value used by Parse Server when you create a Parse Object if the field is not provided.
+`targetClass`: `string`, a Parse Class name used by Parse Server to validate the `Pointer`/`Relation`
+
+✅: Supported
+❌: Not Supported
+
+| Type     | -- required -- | -- defaultValue -- | -- targetClass -- |
+| -------- | -------------- | ------------------ | ----------------- |
+| String   | ✅             | ✅                 | ❌                |
+| Boolean  | ✅             | ✅                 | ❌                |
+| Date     | ✅             | ✅                 | ❌                |
+| Object   | ✅             | ✅                 | ❌                |
+| Array    | ✅             | ✅                 | ❌                |
+| GeoPoint | ✅             | ✅                 | ❌                |
+| File     | ✅             | ✅                 | ❌                |
+| Bytes    | ✅             | ✅                 | ❌                |
+| Polygon  | ✅             | ✅                 | ❌                |
+| Relation | ❌             | ❌                 | ✅ (required)     |
+| Pointer  | ✅             | ❌                 | ✅ (required)     |
+
+Example:
+
+```js
+const UserSchema = {
+  className: "_User",
+  fields: {
+    birthDate: { type: "Date" },
+    firstname: { type: "String", required: true },
+    lastname: { type: "String", required: true },
+    tags: { type: "Array" },
+    location: { type: "GeoPoint" },
+    city: { type: "Pointer", targetClass: "City" },
+    friends: { type: "Relation", targetClass: "_User" },
+    zone: { type: "Polygon" },
+  },
+};
+```

_includes/defined-schema/getting-started.md

@@ -0,0 +1,118 @@
+# Getting Started
+
+## Introduction
+
+For use cases in which a pre-defined schema is beneficial or required, you can define class fields, indexes, Class Level Permissions and more
+
+## Quick Start
+
+You can use Defined Schema as in the following example.
+
+```js
+const { ParseServer } = require("parse-server");
+
+const UserSchema = {
+  className: "_User",
+  fields: {
+    birthDate: { type: "Date" },
+    firstname: { type: "String", required: true },
+    lastname: { type: "String", required: true },
+    tags: { type: "Array" },
+    location: { type: "GeoPoint" },
+    city: { type: "Pointer", targetClass: "City" },
+    friends: { type: "Relation", targetClass: "_User" },
+    zone: { type: "Polygon" },
+  },
+  indexes: {
+    tagsIndex: { tags: 1 },
+    // Special _p_ word to create indexes on pointer fields
+    cityPointerIndex: { _p_city: 1 },
+    tagAndCityIndex: { _p_city: 1, tags: 1 },
+  },
+  classLevelPermissions: {
+    find: { requiresAuthentication: true },
+    count: { "role:Admin": true },
+    get: { requiresAuthentication: true },
+    update: { requiresAuthentication: true },
+    create: { "role:Admin": true },
+    delete: { "role:Admin": true },
+    protectedFields: {
+      // These fields will be protected from all other users
+      // authData, and password are already protected by default
+      "*": ["authData", "emailVerified", "password", "username"],
+    },
+  },
+};
+
+const City = {
+  className: "City",
+  fields: {
+    name: { type: "String", required: true },
+    location: { type: "GeoPoint" },
+    country: { type: "Pointer", targetClass: "Country" },
+  },
+  classLevelPermissions: {
+    find: { requiresAuthentication: true },
+    count: { requiresAuthentication: true },
+    get: { requiresAuthentication: true },
+    // Only a user linked into the Admin Parse Role
+    // authorized to manage cities
+    update: { "role:Admin": true },
+    create: { "role:Admin": true },
+    delete: { "role:Admin": true },
+  },
+};
+
+const Country = {
+  className: "Country",
+  fields: {
+    name: { type: "String", required: true },
+  },
+  classLevelPermissions: {
+    find: { requiresAuthentication: true },
+    count: { requiresAuthentication: true },
+    get: { requiresAuthentication: true },
+    // Empty object meas that only master key
+    // is authorized to manage countries
+    update: {},
+    create: {},
+    delete: {},
+  },
+};
+
+ParseServer.start({
+  databaseURI: "mongodb://your.mongo.uri",
+  appId: "myAppId",
+  masterKey: "mySecretMasterKey",
+  serverURL: "http://localhost:1337/parse",
+  port: 1337,
+  publicServerURL: "http://localhost:1337/parse",
+  // Then just register schemas into Parse Server
+  schema: {
+    definitions: [User, City, Country],
+    // Parse Schema API will be disabled
+    // If you need to update schemas Parse server
+    // need to be updated and deployed (CI/CD strategy)
+    lockSchemas: true,
+    // If true, Parse Server will delete non defined Classes from
+    // the database. (Core classes like Role, User are never deleted)
+    strict: true,
+    // If true, a field type change, the changed field is deleted
+    // from the database (all data in this field will be deleted)
+    // and then create the field with the new type
+    recreateModifiedFields: false,
+    // If true, Parse will delete non defined fields on a class. (Core fields are never deleted)
+    deleteExtraFields: false,
+  },
+  serverStartComplete: () => {
+    // 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
+    parseServer.expressApp.get("/ready", (req: any, res: any) => {
+      res.send("true");
+    });
+  },
+});
+```

_includes/defined-schema/indexes.md

@@ -0,0 +1,26 @@
+# Indexes
+
+To optimize the Parse Server performance you can define indexes and compound indexes.
+
+To define an index on a `Pointer` field you need to use a
+special notation `_p_<FIELDNAME>`.
+For example if you define `city: { type: "Pointer", targetClass: "City" }` in your `fields` you can define an index on this pointer with `cityIndexExample: { _p_city: true }`.
+
+Note: Currently Defined Schemas do not support indexes on special `_Join` classes used under the hood by the `Relation` type.
+
+Example:
+
+```js
+const UserSchema = {
+  className: "_User",
+  fields: {
+    tags: { type: "Array" },
+    city: { type: "Pointer", targetClass: "City" },
+  },
+  indexes: {
+    tagsIndex: { tags: 1 },
+    cityPointerIndex: { _p_city: 1 },
+    tagAndCityIndex: { _p_city: 1, tags: 1 },
+  },
+};
+```

_includes/defined-schema/options.md

@@ -0,0 +1,39 @@
+# Options
+
+## definitions
+
+An array of your Defined Parse Classes.
+
+## strict
+
+You can set the `strict` option to `true` if you want Parse Server to delete all Parse Objects when you remove a Defined Parse Class from your `definitions`. Data stored in removed classes will be lost.
+
+`strict` is default to `false`. If you often change your schemas be aware that you will have stale data classes in your database. You will need to delete these classes (collection for MongoDB, table for Postgres) manually, through your database CLI/UI.
+
+## deleteExtraFields
+
+You can set the `deleteExtraFields` option to `true` if you want Parse Server to delete a removed Defined Parse Class field from your database. Data stored in the removed field will be lost.
+
+`deleteExtraFields` is default to `false`. Be aware that you will have stale data fields in your database since Parse Server will not delete field data automatically. You will need to delete these fields manually.
+
+## recreateModifiedFields
+
+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.**
+
+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`.
+
+This option help to keep one source of truth. And prevent developers or custom code to interfere with your schema definitions and data structure, even with the master key.
+
+## beforeMigration
+
+A function called before parse-server performs schema updates based on the `definitions` option
+
+## afterMigration
+
+A function called after parse-server performed schema updates based on the `definitions` option