Version 0.6.2  
Docs

Rules and Document Validation

Rules are the building blocks of Appwrite Database collections. Using rules and their validators you are able to structure your project data and make sure you only get the data in the formats you expect to.

Rule Object

Name Type Description
label required string

Rule display name.

key required string

Rule name. No special characters and no spaces. Max 32 chars.

type required string

Rule key type. Check the rule type lists below for available options.

default required any

Default value for this rule type. Make sure that the default value is able to pass validation in order to avoid errors when skipping optional values.

required required boolean

Decide if this rule value is required in order to pass document validation.

array required boolean

Decide if this rule is a primitive or an array of values.

list optional array

Array of collections unique ID strings. Used only when rule is of type document.

Validation Types

Each rule has a validation type. This data types are abstracted to help you get started as quickly as possible.

Value Description
text Any string value.
numeric Any integer or float value.
boolean Any boolean value.
wildcard Accept any value.
url Any valid URL.
email Any valid email address.
ip Any valid IP v4 or v6 address.
document Accept a valid child document. When using this type you are also required to pass the 'list' parameter with an array of the collections UID values of the document types you want to accept.

Examples

The examples below will show you how you can use the rule objects to define a new Appwrite collection.

The following examples are using the Appwrite Node.js SDK but can be applied similarly to any of the other Appwrite SDKs.

Example #1 - Movies Collection

In this example we are creating a simple movies collection that accepts a name, release year and notes attributes. Out notes attribute will only accept an array of text based values and not a single value.

const appwrite = require('node-appwrite');
    
let client = new appwrite.Client();
let database = new appwrite.Database(client);

client
    .setEndpoint('YOUR_SERVER_ENDPOINT') // http://localhost/v1
    .setProject('YOUR_PROJECT_UID')
    .setKey('YOUR_API_SECRET')
;

let promise = database.createCollection(
    'Movies', // Collection Name
    ['*'], // Read permissions
    ['user:yyy', 'team:xxx'], // Write permissions
    [ // Rules
      {
        "label": "Name",
        "key": "name",
        "type": "text",
        "default": "Empty Name",
        "required": true,
        "array": false
      },
      {
        "label": "Release Year",
        "key": "releaseYear",
        "type": "numeric",
        "default": 1970,
        "required": true,
        "array": false
      },
      {
        "label": "Notes",
        "key": "notes",
        "type": "text",
        "default": null,
        "required": false,
        "array": true
      }
    ]
);

promise.then(function (response) {
    console.log(response);
}, function (error) {
    console.log(error);
});

A valid document for the collection we just created will look like this:

let movie = {
	"name": "Frozen 2",
	"releaseYear": 2019,
	"notes": [
		"This movie is awesome!",
		"I really like the post-credits scene."
	]
};

Example #2 - Nested Documents

In this example, we are creating a simple movies and actors collections. The new movie collection will accept a new actors attribute that will include an array of actor type documents.

const appwrite = require('node-appwrite');

async function boot() {

  let client = new appwrite.Client();
  let database = new appwrite.Database(client);

  client
      .setEndpoint('YOUR_SERVER_ENDPOINT') // http://localhost/v1
      .setProject('YOUR_PROJECT_UID')
      .setKey('YOUR_API_SECRET')
  ;

  let actorsCollection = await database.createCollection(
      'Actors', // Collection Name
      ['*'], // Read permissions
      ['user:yyy', 'team:xxx'], // Write permissions
      [ // Rules
        {
          "label": "Name",
          "key": "name",
          "type": "text",
          "default": "Empty Name",
          "required": true,
          "array": false
        },
      ]
  );

  let moviesCollection = await database.createCollection(
      'Movies', // Collection Name
      ['*'], // Read permissions
      ['user:yyy', 'team:xxx'], // Write permissions
      [ // Rules
        {
          "label": "Name",
          "key": "name",
          "type": "text",
          "default": "Empty Name",
          "required": true,
          "array": false
        },
        {
          "label": "Release Year",
          "key": "releaseYear",
          "type": "numeric",
          "default": 1970,
          "required": true,
          "array": false
        },
        {
          "label": "Actors",
          "key": "actors",
          "type": "document",
          "default": null,
          "required": false,
          "array": true,
          "list": [actorsCollection['$id']] // Name the collections unique IDs that are allowed in the attribute
        }
      ]
  );

  let response = await database.createDocument(
    moviesCollection['$id'], // Parent collection unique ID
    {
      "name": "Frozen 2",
      "releaseYear": 2019,
      "actors": [
        {
          "$collection": actorsCollection['$id'], // The actors collection unique ID
          "$permissions": {"read": ["*"], "write": ['user:yyy', 'team:xxx']}, // Set document permissions
          "name": "Idina Menzel"
        },
        {
          "$collection": actorsCollection['$id'], // The actors collection unique ID
          "$permissions": {"read": ["*"], "write": ['user:yyy', 'team:xxx']}, // Set document permissions
          "name": "Kristen Bell"
        }
      ]
    },
    ['*'], // Read permissions
  );

  console.log(response);
}

boot();

Note that child document must declare both their unique collection ID and permissions settings individually, to help the Appwrite API run the correct set of validation rules on your input.