App data schema

5 min

Data in Optimizely Connect Platform (OCP) is stored in collections called objects (also known as a database table). Objects are composed of fields (database table columns). You can link objects together using relationships.

Objects – Act as database tables and store collections of data. Objects contain fields that are the names of the table columns. Objects are connected to other objects by relationships.

Fields – Represent columns in a database table. Each object has a primary key field, which must be a string or a number. Fields have one of the following data types:

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

number – Represented in standard decimal or integer format (for example: 0, 3.14159, -2.3, -0.112).

boolean – Must be 0, 1, true, or false.

timestamp – Must be ISO 8601 format or UNIX epoch (seconds since January 1, 1970). For example, 1435708800, 2015-07-01T00:00:00-00:00, 2015-07-01T12:30:00-07:00.

If time and timezone are not provided, the system assumes 12 a.m. UTC for the time.

Relationships – 1:1 database table relationships.

You can view your data schema in the OCP UI.

Important

You must prefix object names with your app ID, and prefix the object display names with your app display name. For example, if your app ID is my_app and the display name is My App, prefix object names with my_app, like my_app_customer_service_tickets, and prefix object display names with My App, like My App Customer Service Tickets.

You do not have to do this for fields within an object that your app creates.

When users install and upgrade your app, OCP makes sure objects, fields, and relationships declared in the app's YAML files are created in the OCP account where the user is installing and upgrading the app.

Change OCP schema with caution. After you create an object or field, you cannot delete or rename it.

YAML file properties for defining objects and fields

The following table lists the properties and their descriptions for YAML files that define objects.

Property	Description
`name`	The name of the object (should be plural). Must be globally unique. You must prefix custom object names with your `app_id`.
`display_name`	The user-friendly name used for display within the UI (should be plural). You must prefix custom object names with your app name.
`alias`	(Optional) The singular name of the object.
`fields.name`	The name of the field used for API calls, SDK calls, and CSV uploads. Must be unique within the object.
`fields.display_name`	The user-friendly name used for display within the UI. Must be unique within the object.
`fields.type`	Must be `string`, `number`, `boolean`, or `timestamp`.
`fields.primary`	(Optional) Boolean. Defaults to `false`. `true` – The field listed is the primary key for the containing object.\ `false` – The field listed is not 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. Use `relations` to connect objects together.
`relations.name`	The name of the relationship used for API and SDK calls.
`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 data schema

When users install your app, OCP parses files within src/schema and creates described objects, fields, and relationships. To add a custom object, create a file named <plural_object_name>.yml within the src/schema folder. For example, a file named acme_tickets.yml for the acme_tickets object.

The file names within the src/schema folder must match the name of an existing object or the name of the custom object you want to create.

Below is an example of an src/schema/acme_tickets.yml file:

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