Schema

The Basics

Term	Definition
Object	Objects are database tables, acting as collections of client data. Objects contain fields that are the names of the table columns. Objects are connected to other objects via relationships.
Field	Fields are columns within the table (an Object within OCP). All objects have one primary key field that must be a string or number. Fields have a data type and can be `string` \| `number` \| `boolean` \| `timestamp` `string` is any printable UTF-8 character, including space. Text is limited to 1024 characters. `number` is represented in standard decimal or integer format (Example: `0`, `3.14159`, `-2.3`, `-0.112`) `timestamp` must be formatted as ISO 8601 format or UNIX epoch (seconds since January 1, 1970). Examples: `1435708800`, `2015-07-01T00:00:00-00:00`, `2015-07-01T12:30:00-07:00` Note: If time and timezone are not provided, the system assumes 12am UTC for the time. `boolean` must be one of `0`, `1`, `true` or `false`
Relationship	Relationships are database table relationships. 1:1 relationships are currently supported.

Term

Definition

Object

Objects are database tables, acting as collections of client data.

Objects contain fields that are the names of the table columns.

Objects are connected to other objects via relationships.

Field

Fields are columns within the table (an Object within OCP).

All objects have one primary key field that must be a string or number.

Fields have a data type and can be string | number | boolean | timestamp

string is any printable UTF-8 character, including space. Text is limited to 1024 characters.

number is represented in standard decimal or integer format (Example: 0, 3.14159, -2.3, -0.112)

timestamp must be formatted as ISO 8601 format or UNIX epoch (seconds since January 1, 1970). Examples: 1435708800, 2015-07-01T00:00:00-00:00, 2015-07-01T12:30:00-07:00
Note: If time and timezone are not provided, the system assumes 12am UTC for the time.

boolean must be one of 0, 1, true or false

Relationship

Relationships are database table relationships.

1:1 relationships are currently supported.

🚧
Important
All objects and fields that are unique to your app must be prefixed with your app_id.
For example, if your app_id is acme, you must prefix all of your objects and fields on objects you created with acme.
The exception to this is fields within an object that your app create (for example, if your app created acme_tickets then you do not have to prefix fields within this object).

Create Static Schema

All files within src/schema are parsed at install time and described objects and fields are created.

📘
Note
The file names of files within src/schema must match the name of an existing object or the name of the newly created object you wish to create.

name: acme_tickets
display_name: Acme Tickets
alias: acme_ticket
fields:
  - name: acme_ticket_id
    display_name: Acme Ticket ID
    type: string
    primary: true
  - name: tag_id
    display_name: Tag ID
    type: string
relations:
  - name: acme_ticket_tag
    display_name: Acme Ticket Tag
    child_object: acme_ticket_tags
    join_fields:
      - parent: tag_id
        child: acme_ticket_tag_id

Property
name	The name of object (should be plural)
display_name	The user-friendly name used for display within the UI (should be plural)
alias	The singular name of the object
fields.name	The name of the field used for API/SDK calls, CSV uploads and Liquid
fields.display_name	The user-friendly name used for display within the UI
fields.type	One of `string` \| `number` \| `boolean` \| `timestamp`
fields.primary	Boolean. Optional. Defaults to `false`. Whether or not the field listed is the primary key for the containing object. At least one primary key is required for new objects!
relations	Optional. Should be defined on the parent object.
relations.name	The name of the relationship used for API/SDK calls and Liquid.
relations.display_name	The user-friendly name used for display within the UI.
relations.child_object	The child object that is connected to this object.
relations.join_fields.parent	Any field on this object that you want to relate to another object.
relations.join_fields.child	Must be a primary key on the child object.

Create Dynamic Schema

(For example, custom fields per client)

You often need to create fields that are client-specific. These objects and fields cannot be created via the Schema .yml files because they differ for each install. OCP provides a number of methods to create fields programmatically.

Find the latest SDK reference in our reference for Fields, Objects & Relationships.

import {z} from '@zaius/node-sdk';

z.schema.createObject({
  'name': 'acme_tickets',
  'display_name': 'Acme Tickets',
  'alias': 'acme_ticket',
  'fields': [
    {
      'name': 'acme_ticket_id',
      'display_name': 'Acme Ticket ID',
      'type': 'string',
      'primary': true
    },{
      'name': 'tag_id',
      'display_name': 'Tag ID',
      'type': 'string'
    }
  ],
  'relations': [
    {
      'name': 'acme_ticket_tag',
      'display_name': 'Acme Ticket Tag',
      'child_object': 'acme_ticket_tags',
      'join_fields': [{
        'parent': 'tag_id',
        'child': 'acme_ticket_tag_id'
      }]
    }
  ]
});

import {z} from '@zaius/node-sdk';

z.schema.createField('acme_tickets', {
    'name': 'tag_id',
    'display_name': 'Tag ID',
    'type': 'string'
});

import {z} from '@zaius/node-sdk';

z.schema.createRelation('acme_tickets', {
    'name': 'acme_ticket_tag',
    'display_name': 'Acme Ticket Tag',
    'child_object': 'acme_ticket_tags',
    'join_fields': [{
        'parent': 'tag_id',
        'child': 'acme_ticket_tag_id'
    }]
});

Schema

The Basics

🚧
Important

Create Static Schema

📘
Note

Create Dynamic Schema

The Basics

🚧Important

Create Static Schema

📘Note

Create Dynamic Schema

🚧
Important

📘
Note