docs: add defined schema docs

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

@@ -0,0 +1,59 @@
+# Class Level Permissions
+
+Setting Class level permissions through Defined Schema is a good first step into security systems available on Parse Server.
+
+## CLP Keys
+
+These CLP keys 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 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.
+
+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
+
+Available options for CLP keys:
+
+- `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 Key
+
+This CLP key is powerful and need some additional explanation.
+We will take the Parse User class as example.
+
+```js
+{
+    protectedFields: {
+      "*": ["authData", "emailVerified", "password", "username"],
+    },
+}
+```
+
+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.
+
+But protected fields could be combined for example.
+
+```js
+{
+    protectedFields: {
+      "*": ["authData", "emailVerified", "password", "username", "phone", "score"],
+      "role:Admin": ["password", "authData", "emailVerified"],
+      "role:VerifiedUser": ["password", "authData", "emailVerified", "score"],
+    },
+}
+```
+
+In this case, a user member of the Parse Role `Admin` will be able to get the `phone` and `score` of another User. A user member of the Parse Role `VerifiedUser` can only get `phone`.
+If a 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 will never delete these classes/fields if not provided in `schema` option.
+
+- `_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,34 @@
+# Fields
+
+You can find here all field types available on Parse
+
+- `Number`: this type support `required` and `defaultValue`
+- `String`: this type support `required` and `defaultValue`
+- `Boolean`: this type support `required` and `defaultValue`
+- `Date`: this type support `required` and `defaultValue`
+- `Object`: this type support `required` and `defaultValue`
+- `Array`: this type support `required` and `defaultValue`
+- `GeoPoint`: this type support `required`
+- `File`: this type support `required`
+- `Bytes`: this type support `required`
+- `Polygon`: this type support `required`
+- `Relation`: You need to provide `targetClass`
+- `Pointer`: You need to provide `targetClass`, this type support `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,122 @@
+# Getting Started
+
+## Introduction
+
+Parse Server was historically designed to be a schema less system. You didn't have to perform migration and define specific database schemas at start up time.
+But schema less do not fulfill each use case of developers and could also do not play very well with some new Parse Server features like the GraphQL API.
+
+To meet these needs, Parse Server now introduce Defined Schemas feature.
+Define easily you Parse Classes fields, indexes, Class level permissions and more.
+
+## Quick Start
+
+To leverage the power of Defined Schema we recommend to setup parse user like an express app.
+
+```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: true,
+    // If true, Parse will delete non defined fields on a class. (Core fields are never deleted)
+    deleteExtraFields: true,
+  },
+  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 you Parse Server database performance you can define indexes and compound indexes.
+
+To define an index on a `Pointer` field you need to use a
+special notation `_p_myFieldName`.
+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
+
+You classes definitions stored in an `Array`.
+
+## 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.
+
+`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.
+
+`deleteExtraFields` is default to `false`. Be aware that some stale fields could exists in your database. You will need to delete these fields manually.
+
+## recreateModifiedFields
+
+You can set the `recreateModifiedFields` option to `true` if you 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