HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog 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).

TermDefinition
ObjectObjects 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.
FieldFields 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
RelationshipRelationships 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 creates (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
PropertyDescription
nameThe name of object (should be plural)
display_nameThe user-friendly name used for display within the UI (should be plural)
aliasThe singular name of the object
fields.nameThe name of the field used for API/SDK calls, CSV uploads and Liquid
fields.display_nameThe user-friendly name used for display within the UI
fields.typeOne of string | number | boolean | timestamp
fields.primaryBoolean. 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!
relationsOptional. Should be defined on the parent object.
relations.nameThe name of the relationship used for API/SDK calls and Liquid.
relations.display_nameThe user-friendly name used for display within the UI.
relations.child_objectThe child object that is connected to this object.
relations.join_fields.parentAny field on this object that you want to relate to another object.
relations.join_fields.childMust 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'
    }]
});

Next