Schemas

A schema defines both the data contained and the behavior (in the form of a state machine) of the documents it holds. A Schema object is identified within the Data Service by a unique identifier (id) and contains a name (3-50 characters) and description (max 100 characters). A schema is based on:

• Permissions that determine who can access what documents,

• Statuses which define the state of the document,

• Properties which define the structure of the document,

• Transitions which can trigger actions

Create a new schema

JavaScript

const myNewSchema = await exh.data.schemas.create({
    name: 'myNewSchema',
    description: 'This is my new schema',
});

Data Access Management

In this section we discuss how you can configure access to documents. A schema contains specific attributes that define the conditions which must be met to create, view, update or delete documents.

Access Modes

createMode

createMode defines the permissions needed to create a document in a schema collection.

Mode	Description
default	The default mode allows every logged-in user to create a new document in the collection. When no createMode is set, this mode will be used.
permissionRequired	Only users with CREATE_DOCUMENTS or CREATE_DOCUMENTS:{schemaName}permission have the ability to create a document.

readMode

readMode defines the permissions needed to read a document in a schema collection

Mode	Description
default	All users where their userId is in the list of userIds attached to the document or if they have a staff enlistment in a group that is in the list of groupIds of the document.
allUsers	All users will have the permission to read the documents in the schema collection.
enlistedInLinkedGroups	All users that have a staff enlistment or a patient enlistment in a group that is in the list of groupIds of the document.

Users that have the VIEW_DOCUMENTS or VIEW_DOCUMENTS:{schemaName}permission attached to a global role will be able to read any document regardless of the setting above.

updateMode

updateMode defines the permissions needed to update a document in a schema collection

Mode	Description
default	All users where their userId is in the list of userIds attached to the document or if they have a staff enlistment in a group that is in the list of groupIds of the document
creatorOnly	Only the user that created the document is able to update a document
disabled	Nobody can update a document
linkedGroupsStaffOnly	All users that have a staff enlistment in a group that is in the list of groupIds of the document.

Users that have the UPDATE_DOCUMENTS or UPDATE_DOCUMENTS:{schemaName}permission attached to a global role will be able to update any document regardless of the setting above.

deleteMode

deleteMode defines the permissions needed to remove a document permanently from a schema collection.

Mode	Description
permissionRequired	Only users with theDELETE_DOCUMENTS or DELETE_DOCUMENTS:{schemaName}permission will be able to remove a document. [default]
linkedUsersOnly	All users where their userId is in the list of userIds attached to the document.

Users that have the DELETE_DOCUMENTS or DELETE_DOCUMENTS:{schemaName}permission attached to a global role will be able to delete any document regardless of the setting above.

Access to documents through role permissions

Every permission has a global and a schema-specific variant. This allows you to define access to documents in a very granular way.

The following table lists the relevant permissions for the data service:

Permission	Description
VIEW_DOCUMENTS	A user with this permission can view all documents in any schema
VIEW_DOCUMENTS:{schemaName} since 1.1.0	A user with this permission can view all documents in a specific schema schemaName
CREATE_DOCUMENTS	A user with this permission can create documents in any schema
CREATE_DOCUMENTS:{schemaName} since 1.1.0	A user with this permission can create documents in a specific schema schemaName
UPDATE_DOCUMENTS	A user with this permission can update all documents in any schema
UPDATE_DOCUMENTS:{schemaName} since 1.1.0	A user with this permission can update all documents in a specific schema schemaName
DELETE_DOCUMENTS	A user with this permission can delete any document in any schema
DELETE_DOCUMENTS:{schemaName} since 1.1.0	A user with this permission can delete any document in schema schemaName
CREATE_DOCUMENT_COMMENTS deprecated	A user with this permission can create comments in any document in any schema
CREATE_DOCUMENT_COMMENTS:{schemaName} since 1.1.0 deprecated	A user with this permission can create comments in any document in schema schemaName
VIEW_DOCUMENT_COMMENTS deprecated	A user with this permission can view comments in any document in any schema
VIEW_DOCUMENT_COMMENTS:{schemaName} since 1.1.0 deprecated	A user with this permission can view comments in any document in schema schemaName
UPDATE_DOCUMENT_COMMENTS deprecated	A user with this permission can update any document comments in any schema
UPDATE_DOCUMENT_COMMENTS:{schemaName} since 1.1.0 deprecated	A user with this permission can update any document comments in schema schemaName
UPDATE_ACCESS_TO_DOCUMENT	A user with this permission can update the access to any document in any schema
UPDATE_ACCESS_TO_DOCUMENT:{schemaName} since 1.1.0	A user with this permission can update the access to any document in schema schemaName

The above mentioned permissions can be granted to users through global roles or group roles.

For more information how to add permissions to roles and roles to users, take a look at the user service documentation

Creating a schema with permissions

You can provide the permissions parameters upon creation of you new schema:

const myNewSchema = await exh.data.schemas.create({
    name: 'myNewSchema',
    description: 'This is my new schema',
    createMode: 'default',
    readMode: 'allUsers',
    updateMode: 'disabled',
    deleteMode: 'permissionRequired'
});

Properties

A Schema defines the structure of a document through properties. The Properties object contains type configurations, which represent the fields that should be accepted while creating or updating a document. The structure of the type configurations themselves is inspired by JSON Schema.

The Data Service supports five kinds of configurations (type attribute):

Type	Description
object	A container object to define multiple objects, in which each object must meet the schema defined in the properties attribute
array	An array object in which each value must meet the schema defined by the items attribute
string	A string object of which each value must meet the schema defined by the pattern, format, enum and/or const attributes,
number	A number object of which each value must meet the schema defined by the enum or const attribute,
boolean	A boolean object of which each value must meet the schema defined by the enum or const attribute.

Object

{
  type: 'object',
  properties: {
    my_custom_field: { type: 'string' },
  },
  additionalProperties: { type: 'string' },
  required: ['my_custom_field'],
}

References:

• JSON Schema: Keywords for Applying Subschemas to Objects

• JSON Schema Validation: Validation Keywords for Objects

Array

{
  type: 'array',
  items: { type: 'string' },
  minItems: 1,
  maxItems: 10,
  contains: { type: 'string' },
}

Note that the items- property is required.

References:

• JSON Schema: Keywords for Applying Subschemas to Arrays

• JSON Schema Validation: Validation Keywords for Arrays

String

{
  type: 'string',
  minLength: 1,
  maxLength: 10,
  pattern: '^[a-z]+$',
  format: 'date-time', // The only supported format is `date-time`
  enum: ['a', 'b', 'c'],
  const: 'b' // Can only be one fixed string
}

When the format is set to date-time, input is expected to be valid ISO 8601 string (e.g.2012 or 2012‐08‐22T14:16:05.677+02:00).

This value is stored as an UTC Date Time String (e.g. 2012‐08‐22T12:16:05.677Z).

Input conditions will operate on the input (e.g.2012 or 2012‐08‐22T14:16:05.677+02:00). Document conditions will operate on the stored date, thus the UTC Date Time String (e.g. 2012‐08‐22T12:16:05.677Z).

References:

• JSON Schema Validation: Validation Keywords for Strings

• JSON Schema Validation: Dates, Times, and Duration

• JSON Schema Validation: Validation Keywords for Any Instance Type

Number

{
  type: 'number',
  minimum: 1,
  maximum: 5,
  enum: [1, 2, 3, 4, 5],
  const: 3 // Can only be 1 number
}

References:

• JSON Schema Validation: Validation Keywords for Numeric Instances

• JSON Schema Validation: Validation Keywords for Any Instance Type

Boolean

{
  type: 'boolean',
  enum: [true, false],
  const: true, // Can only be either true or false
}

References:

• JSON Schema Validation: Validation Keywords for Any Instance Type

Adding properties to your schema

Javascript

await exh.data.properties.create(newSchema.id, { name: 'myFirstProperty',
    configuration: {
      type: 'string',
      enum: ['firstValue', 'secondValue'],
    }
});

Updating properties

You can update a specific property of a schema by providing the schema Id, the property path and the the json schema field configuration. The Property path makes use of the dot notation in case you are working with nested fields.

Javascript

await exh.data.properties.update(mySchema.id,'myObjectField.myStringField',{
    type:"string"
});

Removing properties

You can remove a specific property of a schema by providing the schema Id, the property path and the the json schema field configuration. The Property path makes use of the dot notation in case you are working with nested fields.

Javascript

await exh.data.properties.remove(mySchema.id,'myObjectField.myStringField',{
    type:"string"
});

Some examples

you can also make more complex objects and array's of objects.

Object example

await exh.data.properties.create(newSchema.id, 
  {
    name: 'address',
    configuration: {
      type: 'object',
      properties: {
        street: {type: 'string', minLength: 1, pattern: '^[a-z]+$'},
        number: {type: 'number', minimum: 1, maximum: 300},
        inhabited: {type: 'boolean', enum: [true, false]},
        residents: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 10}
      }
    }
  }
});

Array example

await exh.data.properties.create(newSchema.id, 
  {
    name: 'relatives',
    configuration: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          name: {type: 'string', minLength: 1, maxLength: 50},
          relation: {type: 'string', enum:['relative','family','friend']}
        }
      }
    }
  }
});

Date-time

await exh.data.properties.create(newSchema.id, 
  {
    name: 'birthdate',
    configuration: {
      type: 'string',
      format: 'date-time'
    }
  }
});

this allows you to create a ISO formatted date-time field wich accepts RQL to query on using gt,gte, lt and lte ,...

All attributes required to compose the type configurations, can be found in the API reference documentation and on the JSON Schema webpage.

Statuses

A document can be perceived as a finite-state machine, which remains in a state/status until a transition occurs. You can define a set of statuses for your document based on the expected workflow you want to build.

Javascript

await exh.data.statuses.create(newSchema.id, {
    name: 'initialStatus',
});

CreationTransition

The creation transition is the transition that is executed when you create a document. It is the only type of transition that doesn't have a fromStatus as there is no status to start from.

When you create new schema, by default the data service will include a NEW status and a creation transition towards that status. This is the reason why you wont find a create creationTransition or delete creationTransition function and only an updateCreationTransition function.

Javascript

exh.data.transitions.updateCreation(newSchema.id,{
    type: 'manual',
    toStatus: 'initialStatus',
    conditions: {...},
    actions: {...},
    afterActions: {...}
});

Currently the only supported transition type is manual. Other types may be added in the future.

Transitions

When you want to add more statuses to your document you will need to define transitions that allow you to move your document from one status to another. Normal transitions look the same as a creationTransition but these do include two additional parameters fromStatusesand name.

A Transition occurs from one Status to another. The Statuses a Transition starts from are determined in the fromStatuses object, and the Status the Transition leads to is determined in the toStatus attribute.

Javascript

exh.data.transitions.updateCreation(newSchema.id,{
    name: 'firsTransition'
    type: 'manual',
    fromStatuses: ['initialStatus'],
    toStatus: 'secondStatus',
    conditions: {...},
    actions: {...},
    afterActions: {...}
});

A Transition object is identified by its name (name) and has a specific type assigned:

Types

Type	Description
Manual	A manual transition will be triggered when the transition execution endpoint is called on the document.
Automatic	An automatic transition will trigger when its conditions are met. E.g. when a document is transitioned to status A the data service will look for any automatic transitions that have status A mentioned as a fromStatus. If the conditions of that transition are met it will execute. If not the data service will go to the next automatic transition in line. The sequence of the transitions will depend on the sequence of configuration.

Transition conditions

Conditions need to be met before a transition can occur. There are three types of conditions which apply to the creationTransition and Transitions with the type manual:

Type	Description
input	The transition data must match a desired form, as specified by the type configurations in the configuration attribute.
initiatorHasRelationToUserInData	The initiator of the Transition has a specified relation (as determined in relation) to a user (as determined in userIdField) mentioned in the transition data
initiatorHasRelationToGroupInData	The initiator of the Transition has a specified relation (as determined in relation) to a group (as determined in groupIdField) mentioned in the transition data

There is an additional condition which applies to all Transitions:

Type	Description
document	The content of a document must match a desired form, as specified by the type configurations in the configuration attribute

Input Condition

The transition data must match a desired form, as specified by the type configurations in the configuration attribute.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition requiring:

• The name in the input to be a string

• The name in the input to exist

JavaScript

await exh.data.transitions.create(newSchema.id, {
    type: 'manual',
    name: 'firstTransition',
    fromStatuses: ['initialStatus'],
    toStatus: 'secondStatus',
    conditions: [
      {
        type: 'input',
        configuration: {
          type: 'object',
          properties: {
            name: {
              type: 'string',
            },
          },
          required: ['name'],
        },
      },
    ],
  });

initiatorHasRelationToUserInData Condition

The initiator of the Transition has a specified relation (as determined in relation) to a user (as determined in userIdField) mentioned in the transition data.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition requiring:

• The initiator of the transition to be staff of the user with id 5e9fff9d90135a2a9a718e2f.

JavaScript

await exh.data.transitions.create(newSchema.id, {
    type: 'manual',
    name: 'firstTransition',
    fromStatuses: ['initialStatus'],
    toStatus: 'secondStatus',
    conditions: [
      {
        type: 'initiatorHasRelationToUserInData',
        userIdField: '5e9fff9d90135a2a9a718e2f',
        relation: 'isStaffOfTargetPatient'
      },
    ],
  });

initiatorHasRelationToGroupInData Condition

The initiator of the Transition has a specified relation (as determined in relation) to a group (as determined in groupIdField) mentioned in the transition data.

This Condition only applies to the creationTransition and Transitions with type manual.

Example

The following code creates a manual transition requiring:

• The initiator of the transition to be a staff member of the group with id 5e9fff9d90135a2a9a718e2f.

• The initiator of the transition to have the MY_OWN_PERMISSION group permission.

JavaScript

await exh.data.transitions.create(newSchema.id, {
    type: 'manual',
    name: 'firstTransition',
    fromStatuses: ['initialStatus'],
    toStatus: 'secondStatus',
    conditions: [
      {
        type: 'initiatorHasRelationToGroupInData',
        groupIdField: '5e9fff9d90135a2a9a718e2f',
        relation: 'staff',
        requiredPermission: 'MY_OWN_PERMISSION'
      },
    ],
  });

Document Condition

The content of the existing document must match a desired form, as specified by the type configurations in the configuration attribute.

This Condition applies to all transitions.

Example

The following code creates a manual transition requiring:

• The name in the document data to be a string

• The name in the document data to exist

JavaScript

await exh.data.transitions.create(newSchema.id, {
    type: 'manual',
    name: 'firstTransition',
    fromStatuses: ['initialStatus'],
    toStatus: 'secondStatus',
    conditions: [
      {
        type: 'document',
        configuration: {
          type: 'object',
          properties: {
            data: {
              type: 'object',
              properties: {
                name: {
                  type: 'string',
                },
              },
              required: ['name'],
            },
          },
          required: ['data'],
        },
      },
    ],
  });

Transition actions

You can attach actions to transitions. This way when a transition is executed and its conditions are met it will also trigger the action. In case of a Creation Transition, the action will be executed during the creation of the document.

Modifying the document

Action Type	Description
set	Change the value of a specific field.
unset	Remove one or multiple fields.
addItems	Add values to an array field.
removeItems	Removes values from an array field

To access an element in an array or embedded documents, use the dot notation.

code examples

set

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'set',
      field: 'data.myField',
      value: 'myValue'
    }
  ],
  ...
})

unset

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'unset',
      fields: ['data.myField', 'otherField']
    }
  ],
  ...
})

addItems

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'addItems',
      field: 'data.myField',
      values: ['item1', 'item2']
    }
  ],
  ...
})

removeItems

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'removeItems',
      field: 'data.myField',
      values: ['item1', 'item2']
    }
  ],
  ...
})

Modifying document access

Each document has a userIds and groupIds field. These field are part of determining the access policy towards that specific document depending on the general collection schema configuration.

Using actions you can modify these fields and therefore the access of the document.

Action Type	Description
linkCreator	Add the creatorId to the userIds of the document
linkUserFromData	Add a user id found in data of the document to the userIds of the document
linkEnlistedGroups	Add all groups where the creator of the document has a patient enlistment for to the groupIds of the document
linkGroupFromData	Add a group id found in data of the document to the groupIds field of the document

If you like to modify the access to documents from outside the data service you can perform access modification functions on the documents itself. Read the documentation here: #updating-access

code examples

linkCreator

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'linkCreator'
    }
  ],
  ...
});

linkUserFromData

await sdk.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'linkUserFromData',
      userIdField: '{UserIdField}', // Field in dot notation. The root is data
    }
  ],
  ...
})

linkEnlistedGroups

await sdk.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'linkEnlistedGroups',
      onlyActive: true, // Optional, defaults to false
    }
  ],
  ...
});

LinkGroupFromData

await sdk.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'linkGroupFromData',
      groupIdField: 'my_group_id', // Field in dot notation. The root is data
    }
  ],
  ...
});

Other actions

Action Type	Description
Task	trigger the creation of a Task in the Task Service by using the task action. Specify the functionName (which references the AWS Lambda function) and optionally extra data as key-value pairs in the data variable.

code examples

Task

await exh.data.transitions.create(newSchema.id, {
  ...,
  actions: [
    {
      type: 'task',
      functionName: 'myTaskServiceFunctionName'
    }
  ],
  ...
})

Indexes

The Index object is identified by an id and a name. An index is set on a specific property in a Schema. This property is defined in the Fields object by the name and type attribute. The index is tailored with the following attributes:

Attribute	Description
background	A boolean value to determine whether the index must be built in the background; meaning it will take longer but active read and write operations are prioritized.
unique	A boolean value to determine whether the index must be unique
sparse	A boolean value to determine whether the index must be sparse
system	A boolean value to determine whether the index must be

Other settings

groupSyncMode

The groupIds field allows to define which groups should get access to the document. The users that have a staff enlistment in a group that is in the groupIds field will get access to the document. The level of access depends on the readMode, writeMode, updateMode and deleteMode values.

When a groupSyncMode is configured, the data service will automatically update the groupIds field of documents in the schema depending on changes in the user service. The table below lists the different options.

Mode	Description
disabled	The groupIds field is not automatically updated.
creatorPatientEnlistments	All the groups where the user that created the document (creatorId) is enlisted as a patient will be automatically added to the groupIds field.
linkedUsersPatientEnlistments	The groups that contain the users defined in the userIds as a patient are added to the groupIds field.

The synchronization is applied retroactively. It will be applied to all documents in a schema. That includes the documents that were created before configuring this setting and the documents that were created before the user was added to a group.

Example 1 • Allow doctors to access measurements created by patients

When you define a measurements schema, the patients will be the users creating the measurement documents. The creatorId of a measurement will be set to the patient userId.

To automatically give the appropriate doctors access to the measurements of their patients, you can set the groupSyncMode to creatorPatientEnlistments.

Example 2 • Allow doctors to read lab results of patients

Consider the use case where patients can have their saliva tested at kiosks that are deployed in pharmacies. When patients provide a specimen in the kiosk, the kiosk will process the specimen and upload the results. The corresponding document is created by the kiosk, thus creatorId of the document will not correspond to the userId of the patient.

To give doctors access to the results, set the groupSyncMode to linkedUsersPatientEnlistments and configure the kiosk to add the userId of the patient in the userIds field of the document.

Code Example

Javascript

const myNewSchema = await exh.data.schemas.create({
    ...
    groupSyncMode:'creatorPatientEnlistments'
    ...
});

defaultLimit & maximumLimit

The defaultLimit and maximumLimit refer to the number of documents that are returned to you when you execute a query. Pagination is crucial in keeping you API fast and responsive. By default the defaultLimit is set to 20 documents and the maximumLimit is set to 100 documents. We recommend to keep these settings. Only in very specific use cases would it be reasonable to change these settings.

setting
defaultLimit	Defaults to 20. Determines the number of documents returned when no RQL limit parameter is provided.
maximumLimit	Defaults to 100. Determines the number of documents returned when an RQL limit parameter is provided and the maximumLimit is crossed.

Javascript

const myNewSchema = await exh.data.schemas.update(mySchema.id,{
    ...
    defaultLimit:20,
    maximumLimit:200,
    ...
});

Removing a schema

You can only remove disabled schema's. Removing a schema removes all documents in that schema collection. Removed documents are non retrievable.

await exh.data.schemas.enable('{yourSchemaId}');

Enabling/disabling a schema

As the removal of a schema is something that you want to handle with great care the service first requires you to disable a schema. When a schema is disabled creation of new documents is disabled and no changes are allowed to existing documents.

await exh.data.schemas.disable('{yourSchemaId}');

You can enable a disabled schema the same way:

await exh.data.schemas.enable('{yourSchemaId}');