Partner schema configuration

Experience Platform uses schemas to describe the structure of data in a consistent and reusable way. When data is ingested into Platform, it is structured according to an XDM schema. For more information on the schema composition model, including design principles and best practices, see the basics of schema composition.

When building a destination with Destination SDK, you can define your own partner schema to be used by your destination platform. This gives users the ability to map profile attributes from Platform to specific fields that your destination platform recognizes, all within the Platform UI.

When configuring the partner schema for your destination, you can fine tune the field mapping supported by your destination platform, such as:

To understand where this component fits into an integration created with Destination SDK, see the diagram in the configuration options documentation or see the guide on how to use Destination SDK to configure a file-based destination.

You can configure your schema settings via the /authoring/destinations endpoint. See the following API reference pages for detailed API call examples where you can configure the components shown in this page.

This article describes all the supported schema configuration options that you can use for your destination, and shows what customers will see in the Platform UI.

Supported integration types supported-integration-types

Refer to the table below for details on which types of integrations support the functionality described on this page.

Supported schema configuration supported-schema-types

Destination SDK supports multiple schema configurations:

The schemaConfig section uses multiple configuration parameters, depending on the type of schema that you need, as shown in the sections below.

Create a static schema attributes-schema

To create a static schema with profile attributes, define the target attributes in the profileFields array as shown below.

"schemaConfig":{
      "profileFields":[
           {
              "name":"phoneNo",
              "title":"phoneNo",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the mobilePhone.number value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"firstName",
              "title":"firstName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.firstName value in Experience Platform could be firstName on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"lastName",
              "title":"lastName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.lastName value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           }
        ],
      "useCustomerSchemaForAttributeMapping":false,
      "profileRequired":true,
      "segmentRequired":true,
      "identityRequired":true,
      "segmentNamespaceAllowList": ["someNamespace"],
      "segmentNamespaceDenyList": ["someOtherNamespace"]

}

The resulting UI experience is shown in the images below.

When users select the target mapping, they can see the fields defined in the profileFields array.

After selecting the attributes, they can see them in the target field column.

Create a dynamic schema dynamic-schema-configuration

Destination SDK supports the creation of dynamic partner schemas. As opposed to a static schema, a dynamic schema does not use a profileFields array. Instead, dynamic schemas use a dynamic schema server which connects to your own API from where it retrieves the schema configuration.

In a dynamic schema configuration, the profileFields array is replaced by the dynamicSchemaConfig section, as shown below.

"schemaConfig":{
   "dynamicSchemaConfig":{
      "dynamicEnum": {
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"DYNAMIC_SCHEMA_SERVER_ID",
         "value": "Schema Name",
         "responseFormat": "SCHEMA"
      }
   },
   "profileRequired":true,
   "segmentRequired":true,
   "identityRequired":true
}

Required mappings required-mappings

Within the schema configuration, in addition to your static or dynamic schema, you have the option of adding required (or predefined) mappings. These are mappings that users are able to view in the Platform UI, but they cannot modify them when setting up a connection to your destination.

For example, you can enforce the email address field to always be sent to the destination.

See below two examples of a schema configuration with required mappings and what these look like in the mapping step of the activate data to batch destinations workflow.

"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "sourceType": "text/x.schema-path",
        "source": "personalEmail.address",
        "destination": "personalEmail.address"
      }
    ]
}

"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "destination": "identityMap.ExamplePartner_ID",
        "mandatoryRequired": true,
        "primaryKeyRequired": true
      }
    ]
}

Configure support for external audiences external-audiences

To configure your destination to support the activation of externally generated audiences, include the snippet below in the schemaConfig section.

"schemaConfig": {
  "segmentNamespaceDenyList": [],
  ...
}

See the property descriptions in the table further above on this page to learn more about the segmentNamespaceDenyList functionality.

Next steps next-steps

After reading this article, you should have a better understanding of what schema types are supported by Destination SDK and how you can configure your schema.

To learn more about the other destination components, see the following articles: