Data Schemas

Data Schema is used whenever you need to describe the data structure without providing the actual value.

Data Schema we use is based on JSONSchema with additional features.

Additional Properties

Reference Records (Enums or Picklists):

To specify reference records that can be used for a field (for example, to create a field with limited options for selection) use schema like this:

status:
  type: number # Type of `id` keys below
  referenceRecords:
    - name: Open # Title of that option displayed in the UI
      id: 1      # Actual value that will be used after selecting an option
    - name: Won
      id: 2
    - name: Lost
      id: 3

Reference Collection

When working in a context of a Connection, you can point to a specific Data Collection to use its records as possible values for a field.

Example:

ownerId:
  type: string
  referenceCollection:
    key: users
    parameters:
      isActive: true

Is Sensitive

There is an additional property isSensitive (boolean) that can be used to specify that the field contains sensitive information and should be treated accordingly (hidden in the UI, excluded from logs, etc).

Example:

password:
  type: string
  isSensitive: true

Dynamic Data Schema

You can use Formulas in data schemas to make them dynamic. For example:

parent:
  type: object
  properties:
    type:
      type: string
      enum: ['tasks', 'projects']
    id:
      type: string
      referenceCollection:
        key:
          $var: parent.type

In this, parent.id property will reference the tasks collection if parent.type is tasks and the projects collection if parent.type is projects.

Schema will be evaluated in the context of the current value the schema is applied to.

It works in a special way for array schemas: when evaluating dynamic schemas, all arrays leading to the current value will be replaced with the current item that is being evaluated.

For example:

parents:
  type: array
  items:
    type: object
    properties:
      type:
        type: string
        enum: ['tasks', 'projects']
      id:
        type: string
        referenceCollection:
          key:
            $var: parents.type

Notice the locator in the id field: parents.type. It treats parents as if it was an object rather than array. When evaluated, it will use the current item of the parents array.

For example, if the schema is applied to the following object:

parents:
  - type: tasks
    id: 1
  - type: projects

The schema for the first item of the parents list will be the following:

type: object
properties:
  type:
    type: string
    enum: ['tasks', 'projects']
  id:
    type: string
    referenceCollection:
      key: tasks

But for the second item, it will be:

type: object
properties:
  type:
    type: string
    enum: ['tasks', 'projects']
  id:
    type: string
    referenceCollection:
      key: projects