HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityLog In

Schema

This topic describes how to create custom objects and fields for your app using Optimizely Data Platform (ODP) and Optimizely Connect Platform (OCP).

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.

๐Ÿšง

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'
    }]
});

Did this page help you?