HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityLog In

Schema Modules

This topic describes how to map data from an external system to Optimizely Data Platform (ODP).

When mapping data from an external system to ODP, you should ensure you map to standard schema whenever possible.

ODP determines the default schema available to clients based on installed app categories. For example, if a user installs a Loyalty & Rewards app, they will see a number of standard objects.

If you choose a category for your app in the app.yml that has a module associated with it, all of those fields are created upon installation.

Loyalty & Rewards

Customers

name: customers
fields:
  - name: loyalty_points_balance
    type: number
    display_name: Loyalty Points Balance
    description: The number of loyalty points that the customer currently has.
  - name: loyalty_referral_code_id
    type: string
    display_name: Loyalty Referral Code ID
    description: The unique Referral Code ID assigned to the customer.
  - name: loyalty_tier_id
    type: string
    display_name: Loyalty Tier ID
    description: The ID of the Loyalty Tier that the customer is associated with.
  - name: loyalty_profile_created_at
    type: ts
    display_name: Loyalty Profile Created At
    description: The date & time that the customer record was created in the connected loyalty app.
  - name: loyalty_profile_updated_at
    type: ts
    display_name: Loyalty Profile Updated At
    description: The date & time that the customer record was last updated in the connected loyalty app.
  - name: loyalty_is_enrolled_member
    type: boolean
    display_name: Loyalty Is Enrolled Member
    description: If true, the customer is currently enrolled in your loyalty program.
relations:
  - name: loyalty_referral_code
    display_name: Loyalty Referral Code
    child_object: loyalty_referral_codes
    join_fields:
      - parent: loyalty_referral_code_id
        child: loyalty_referral_code_id
  - name: loyalty_tier
    display_name: Loyalty Tier
    child_object: loyalty_tiers
    join_fields:
      - parent: loyalty_tier_id
        child: loyalty_tier_id

Events

name: events
fields:
  - name: previous_loyalty_tier_id
    display_name: Previous Loyalty Tier ID
    type: string
    description: The ID of the tier with which the customer was previously associated.
  - name: current_loyalty_tier_id
    display_name: Current Loyalty Tier ID
    type: string
    description: current_loyalty_tier_id
  - name: previous_loyalty_points_balance
    display_name: Previous Loyalty Points Balance
    type: number
    description: The loyalty points balance of the customer before this event.
  - name: current_loyalty_points_balance
    display_name: Current Loyalty Points Balance
    type: number
    description: The loyalty points balance of the customer after this event.
  - name: loyalty_change_in_points
    display_name: Loyalty Change In Points
    type: number
    description: The total change in loyalty points due to this event.
  - name: loyalty_referral_code_id
    display_name: Loyalty Referral Code ID
    type: string
    description: The unique referral code to which this event applies.
  - name: loyalty_referred_customer_email
    display_name: Loyalty Referred Customer Email
    type: string
    description: The email of the customer that was referred.
relations:
  - name: loyalty_referral_code
    display_name: Loyalty Referral Code
    child_object: loyalty_referral_codes
    join_fields:
      parent: loyalty_referral_code_id
      child: loyalty_referral_code_id
  - name: previous_loyalty_tier
    display_name: Previous Loyalty Tier
    child_object: loyalty_tiers
    join_fields:
      parent: previous_loyalty_tier_id
      child: loyalty_tier_id
  - name: current_loyalty_tier
    display_name: Current Loyalty Tier
    child_object: loyalty_tiers
    join_fields:
      parent: current_loyalty_tier_id
      child: loyalty_tier_id

Loyalty Referral Codes

name: loyalty_referral_codes
display_name: Loyalty Referral Codes
alias: loyalty_referral_code
fields:
  - name: loyalty_referral_code_id
    display_name: Loyalty Referral Code ID
    type: string
    description: The unique referral code assigned to a customer.
  - name: referral_url
    display_name: Referral URL
    type: string
    description: The unique referral code URL.
  - name: total_shares
    display_name: Total Shares
    type: number
    description: The number of times that this referral code has been shared.
  - name: total_clicks
    display_name: Total Clicks
    type: number
    description: The total number of clicks of the shared referral code URL.
  - name: order_conversions_count
    display_name: Order Conversions Count
    type: number
    description: The number of orders that have resulted from this referral code.
  - name: order_conversions_amount
    display_name: Order Conversions Amount
    type: number
    description: The dollar amount of the number of orders that have resulted from this referral code.
  - name: expiration_ts
    display_name: Expiration Date & Time
    type: ts
    description: The date & time that the referral code expires (if it does).
  - name: is_expired
    display_name: Is Expired
    type: boolean
    description: Determines whether or not the referral code is expired.

Loyalty Tiers

name: loyalty_tiers
display_name: Loyalty Tiers
alias: loyalty_tier
fields:
  - name: loyalty_tier_id
    display_name: Loyalty Tier ID
    type: string
    description:  The unique identifier for a Loyalty Tier.
  - name: name
    display_name: Name
    type: string
    description: The name of the Loyalty Tier.
  - name: description
    display_name: Description
    type: string
    description: A description of this Loyalty Tier.
  - name: rank
    display_name: Rank
    type: number
    description: The numeric rank of this Loyalty Tier relative to other Loyalty Tiers.
  - name: required_dollar_spend
    display_name: Required Dollar Spend
    type: number
    description: The amount of dollars that a customer is required to spend to reach this Loyalty Tier.
  - name: required_points
    display_name: Required Points
    type: number
    description: The number of points required to reach this Loyalty Tier.
  - name: required_purchases
    display_name: Required Purchases
    type: number
    description: The number of purchases required to reach this Loyalty Tier.

Surveys & Feedback

Customers

name: customers
fields:
  - name: nps_score
    type: number
    display_name: NPS Score
    description: The most recent NPS score provided by the customer.
  - name: nps_group
    type: text
    display_name: NPS Group
    description: The NPS group (Promoter, Passive, Detractor) to which the customer belongs.
    valid_values:
      - promoter
      - passive
      - detractor

Events

name: events
fields:
  - name: survey_id
    type: string
    display_name: Survey ID
    description: The unique identifier of the customer survey.
  - name: survey_question_id
    type: string
    display_name: Survey Question ID
    description: The unique identifier of a question within a customer survey.
  - name: survey_question_response_id
    type: string
    display_name: Survey Question Response ID
    description: The unique identifier of the customer's response to a survey question.
relations:
  - name: survey
    display_name: Survey
    child_object: surveys
    join_fields:
      - parent: survey_id
        child: survey_id
  - name: survey_question
    display_name: Survey Question
    child_object: survey_questions
    join_fields:
      - parent: survey_question_id
        child: survey_question_id
  - name: survey_question_response
    display_name: Survey Question Response
    child_object: survey_question_responses
    join_fields:
      - parent: survey_question_response_id
        child: survey_question_response_id

Survey Questions Results

name: survey_question_responses
display_name: Survey Question Responses
alias: survey_question_response
fields:
  - name: survey_question_response_id
    type: string
    display_name: Survey Question Response ID
    description: The unique identifier of the customer's response to a survey question.
    primary: true
  - name: survey_question_id
    type: string
    display_name: Survey Question ID
    description: The unique identifier of the question within a customer survey to which this response belongs.
  - name: response_as_text
    type: string
    display_name: Response (Text)
    description: The question response as text which is empty if the response is not text! (Refer to other Question Response fields).
  - name: response_as_number
    type: number
    display_name: Response (Number)
    description: The question response as a number which is empty if the response is not a number! (Refer to other Question Response fields).
  - name: response_as_ts
    type: ts
    display_name: Response (Date / Time)
    description: The question response as date/time which is empty if the response is not in date/time format! (Refer to other Question Response fields).
  - name: response_as_boolean
    type: boolean
    display_name: Response (True / False)
    description: The question response as true/false which is empty if the response is not in true/false format! (Refer to other Question Response fields).
  - name: response_as_list
    type: string
    display_name: Response (List)
    description: The question response as a list which is empty if the response is not a list! (Refer to other Question Response fields).

Survey Questions

name: survey_questions
display_name: Survey Questions
alias: survey_question
fields:
  - name: survey_question_id
    type: string
    display_name: Survey Question ID
    description: The unique identifier of a question within a customer survey.
    primary: true
  - name: text
    type: string
    display_name: Question Text
    description: The survey's question text.
  - name: survey_id
    type: string
    display_name: Survey ID
    description: The unique identifier of the customer survey to which this question belongs.
  - name: type
    type: string
    display_name: Question Type
    description: The type of question.
    valid_values:
      - single_choice
      - scale
      - open_ended
      - demographic
      - datetime
      - multiple_choice
      - presentation
      - file_upload
  - name: required 
     type: boolean
    display_name: Is Required Question?
    description: Indicates whether or not the question must be answered by the customer.

Surveys

name: surveys
display_name: Surveys
alias: survey
fields:
  - name: survey_id
    type: string
    display_name: Survey ID
    description: The unique identifier of the customer survey.
    primary: true
  - name: title
    type: string
    display_name: Title
    description: The title of the customer survey.
  - name: language
    type: string
    display_name: Language
    description: The language of the survey in ISO-639-1 format (for example, en-us).
  - name: url
    type: string
    display_name: URL
    description: The full URL at which the survey is/was accessible.
  - name: created_at
    type: ts
    display_name: Created at
    description: The date & time that the survey was created.
  - name: updated_at
    type: ts
    display_name: Updated at
    description: The date & time that the survey was last updated.

Reviews & Ratings

Events

name: events
fields:
  - name: product_review_id
    type: string
    display_name: Product Review ID
    description: The ID of the review relevant to this event (for product reviews).
  - name: product_question_id
    type: string
    display_name: Product Question ID
    description: The ID of the question relevant to this event (for product Q&As).
  - name: product_answer_id
    type: string
    display_name: Product Answer ID
    description: The ID of the answer relevant to this event (for product Q&As).
relations:
  - name: product_review
    display_name: Product Review
    child_object: product_reviews
    join_fields:
      - parent: product_review_id
        child: review_id
  - name: product_question
    display_name: Product Question
    child_object: product_questions
    join_fields:
      - parent: product_question_id
        child: question_id
  - name: product_answer
    display_name: Product Answer
    child_object: product_answers
    join_fields:
      - parent: product_answer_id
        child: answer_id

Product Answers

name: product_answers
display_name: Product Answers
alias: product_answer
fields:
  - name: answer_id
    type: string
    display_name: Answer ID 
    description: The unique ID for this answer.
    primary: true
  - name: product_id
    type: string
    display_name: Product ID
    description: The ID of the product to which this answer relates.
  - name: question_id
    type: string
    display_name: Question ID 
    description: The ID of the question to which this answer relates.
  - name: from_store_owner
    type: boolean
    display_name: From Store Owner?
    description: Whether this answer was provided by the actual store owner.
  - name: verified
    type: boolean
    display_name: Verified?
    description: Whether this answer was left by a verified buyer.
  - name: content
    type: string
    display_name: Content
    description: The overall answer content.
  - name: visible
    type: boolean
    display_name: Visible?
    description: Whether this answer can be seen on the site.
  - name: created_at
    type: timestamp
    display_name: Creation Date
    description: The date and time when this answer was submitted.
  - name: positive_reaction_count
    type: number
    display_name: Positive Reaction Count
    description: The number of users who rated this answer positively.
  - name: negative_reaction_count
    type: number
    display_name: Negative Reaction Count
    description: The number of users who rated this answer negatively.
relations:
  - name: product
    display_name: Product
    child_object: products
    join_fields:
      - parent: product_id
        child: product_id
  - name: product_question
    display_name: Product Question
    child_object: product_questions
    join_fields:
      - parent: question_id
        child: question_id

Product Questions

name: product_questions
display_name: Product Questions
alias: product_question
fields:
  - name: question_id
    type: string
    display_name: Question ID
    description: The unique ID for this question.
    primary: true
  - name: product_id
    type: string
    display_name: Product ID
    description: The ID of the queried product.
  - name: content
    type: string
    display_name: Content
    description: The overall question content.
  - name: visible
    type: boolean
    display_name: Visible?
    description: Whether this question can be seen on the site.
  - name: created_at
    type: timestamp
    display_name: Creation Date
    description: The date and time when this question was submitted.
relations:
  - name: product
    display_name: Product
    child_object: products
    join_fields:
      - parent: product_id
        child: product_id

Product Reviews

name: product_reviews
display_name: Product Reviews
alias: product_review
fields:
  - name: review_id
    type: string
    display_name: Review ID
    description: A unique identifier for this review.
    primary: true
  - name: product_id
    type: string
    display_name: Product ID
    description: The ID of the reviewed product.
  - name: score
    type: number
    display_name: score
    description: The overall score represented by this review.
  - name: positive_reaction_count
    type: number
    display_name: Positive Reaction Count
    description: The number of users who rated this review positively.
  - name: negative_reaction_count
    type: number
    display_name: Negative Reaction Count
    description: The number of users who rated this review negatively.
  - name: title
    type: string
    display_name: Title
    description: The title given to this review.
  - name: content
    type: string
    display_name: Content
    description: The overall review content.
  - name: visible
    type: boolean
    display_name: Visible?
    description: Whether this review can be seen on the site.
  - name: created_at
    type: timestamp
    display_name: Creation Date
    description: The date and time when this review was submitted.
  - name: deleted
    type: boolean
    display_name: Deleted?
    description: Whether this review has been marked for deletion.
  - name: verified
    type: boolean
    display_name: Verified?
    description: Whether this review was left by a verified buyer.
  - name: top_review
    type: boolean
    display_name: Top Review?
    description: Whether this review is marked as a top review for the product.
relations:
  - name: product
    display_name: Product
    child_object: products
    join_fields:
      - parent: product_id
        child: product_id

Product

name: products
fields:
  - name: average_score
    type: number
    display_name: Average Review Score
    description: Average score of all reviews for the product.
  - name: total_reviews
    type: number
    display_name: Total Review Count
    description: Total count of reviews left for the product.
  - name: top_review_id
    type: string
    display_name: Top Review ID
    description: Unique ID of the top review identified for this product.
relations:
  - name: top_review
    display_name: Top Review
    child_object: product_reviews
    join_fields:
      - parent: top_review_id
        child: review_id

Coupon Codes

Events

name: events
fields:
  - name: coupon_code # Definition within the "Base Schema" module.
relations:
  - name: coupon
    display_name: Coupon
    child_object: assigned_coupons
    join_fields:
      - parent: coupon_code
        child: coupon_code
actions:
  - display_name: Coupon Assigned
    description: Triggered when a coupon is assigned to a customer.
    type: coupon
    action: assigned
    fields:
      - coupon_code
  - display_name: Order Purchase
    description: A customer order purchase that included a coupon.
    type: order
    action: purchase
    fields:
      - coupon_code

Coupon Rules

name: coupon_rules
display_name: Coupon Rules
alias: coupon_rule
description: Coupon codes can be associated with a coupon rule. These rules describe what the coupon code can do when used by a customer. For example, a coupon code of SUMMER20-43dha8d7vb may be associated with a coupon rule of SUMMER20.
fields:
  - name: coupon_rule_id
    type: string
    display_name: Coupon Rule ID
    description: The unique ID for this coupon rule.
    primary: true
  - name: name
    type: string
    display_name: Name
    description: A friendly name identifying the sale/occasion this rule might be offered during  (e.g., SUMMER2020).
  - name: discount_percent
    type: number
    display_name: Percent Off
    description: The amount of the discount in percentage points. For example, "5% off" is represented as 5.
  - name: discount_value
    type: number
    display_name: Value Off
    description: The amount of the discount in currency. For example, "$4 off" is represented as 4.
  - name: free_shipping_type
    type: string
    display_name: Free Shipping Type
    description: Describes how the coupon affects shipping. The only accepted values are "none", "partial", "full_order".
    valid_values:
      - none
      - partial
      - full_order
  - name: discount_type
    type: string
    display_name: Discount Type
    description: An identifier for how this discount affects an order. The only accepted values are "per_item_discount", "per_total_discount", "shipping_discount", "free_shipping", or "percentage_discount".
    valid_values:
      - per_item_discount
      - per_total_discount
      - shipping_discount
      - free_shipping
      - percentage_discount
  - name: uses_per_customer
    type: number
    display_name: Max Uses (per Customer)
    description: The number of times each coupon code that follows this rule may be redeemed.
  - name: uses_overall
    type: string
    display_name: Max Uses (all Customers)
    description: The number of times each coupon code that follows this rule can be redeemed across all customers.
  - name: starts_at
    type: timestamp
    display_name: Valid From
    description: The date at which this rule can first be used.
  - name: earned
    type: boolean
    display_name: Earned?
    description: Indicates whether or not the coupon codes following this rule are earned. Common methods include earning a loyalty tier or performing an action (e.g., sharing a product on social media).
  - name: code_prefix
    type: string
    display_name: Prefix
    description: A prefix that would be found at the beginning of every coupon code using this rule.
  - name: code_suffix
    type: string
    display_name: Suffix
    description: A suffix that would be found at the end of every coupon code using this rule.

Assigned Coupons

name: assigned_coupons
display_name: Assigned Coupons
alias: assigned_coupon
description: Contains all the coupons assigned to customers. Each assigned coupon is typically associated with a Coupon Rule that describes what a coupon does.
fields:
  - name: coupon_code
    type: string
    display_name: Coupon Code
    description: The unique ID for this coupon.
    primary: true
  - name: coupon_rule_id
    type: string
    display_name: Coupon Rule ID
    description: The unique ID of the coupon rule that the coupon follows.
relations:
  - name: coupon_rule
    display_name: Coupon Rule
    child_object: coupon_rules
    join_fields:
      - parent: coupon_rule_id
        child: coupon_rule_id

Did this page help you?