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:
phoneNumber
XDM attribute to a phone
attribute supported by your destination platform.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.
All parameter names and values supported by Destination SDK are case sensitive. To avoid case sensitivity errors, please use the parameters names and values exactly as shown in the documentation.
Refer to the table below for details on which types of integrations support the functionality described on this page.
Integration type | Supports functionality |
---|---|
Real-time (streaming) integrations | Yes |
File-based (batch) integrations | Yes |
Destination SDK supports multiple schema configurations:
profileFields
array in the schemaConfig
section. In a static schema, you define every target attribute that should be shown in the Experience Platform UI in the profileFields
array. If you need to update your schema, you must update the destination configuration.profileFields
array. If you need to update your schema, there is no need to update the destination configuration. Instead, the dynamic schema server retrieves the updated schema from your API.The schemaConfig
section uses multiple configuration parameters, depending on the type of schema that you need, as shown in the sections below.
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"]
}
Parameter | Type | Required/Optional | Description |
---|---|---|---|
profileFields |
Array | Optional | Defines the array of target attributes accepted by your destination platform to which customers can map their profile attributes. When using a profileFields array, you can omit the useCustomerSchemaForAttributeMapping parameter entirely. |
useCustomerSchemaForAttributeMapping |
Boolean | Optional | Enables or disables the mapping of attributes from the customer schema to the attributes that you define in the profileFields array.
false . |
profileRequired |
Boolean | Optional | Use true if users should be able to map profile attributes from Experience Platform to custom attributes on your destination platform. |
segmentRequired |
Boolean | Required | This parameter is required by Destination SDK and should always be set to true . |
identityRequired |
Boolean | Required | Set to true if users should be able to map identity types from Experience Platform to the attributes you defined in the profileFields array . |
segmentNamespaceAllowList |
Array | Optional | Defines specific audience namespaces from which users can map audiences to the destination. Use this parameter to restrict Platform users to export audiences from only the audience namespaces that you define in the array. This parameter cannot be used together with segmentNamespaceDenyList .Example: "segmentNamespaceAllowList": ["AudienceManager"] will allow users to map only audiences from the AudienceManager namespace to this destination. To allow users to export any audience to your destination, you can ignore this parameter. If both segmentNamespaceAllowList and segmentNamespaceDenyList are missing from your configuration, users will only be able to export audiences originating from the Segmentation Service. |
segmentNamespaceDenyList |
Array | Optional | Restricts users from mapping audiences to the destination, from the audience namespaces defined in the array. Cannot be used together with segmentNamespaceAllowed . Example: "segmentNamespaceDenyList": ["AudienceManager"] will block users from mapping audiences from the AudienceManager namespace to this destination. To allow users to export any audience to your destination, you can ignore this parameter. If both segmentNamespaceAllowed and segmentNamespaceDenyList are missing from your configuration, users will only be able to export audiences originating from the Segmentation Service. To allow the export of all audiences, regardless of the origin, set "segmentNamespaceDenyList":[] . |
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.
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.
Before you create a dynamic schema, you must create a dynamic schema server.
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
}
Parameter | Type | Required/Optional | Description |
---|---|---|---|
dynamicEnum.authenticationRule |
String | Required | Indicates how Platform customers connect to your destination. Accepted values are CUSTOMER_AUTHENTICATION , PLATFORM_AUTHENTICATION , NONE .
|
dynamicEnum.destinationServerId |
String | Required | The instanceId of your dynamic schema server. This destination server includes the API endpoint which Experience Platform will call to retrieve the dynamic schema. |
dynamicEnum.value |
String | Required | The name of the dynamic schema, as defined in the dynamic schema server configuration. |
dynamicEnum.responseFormat |
String | Required | Always set to SCHEMA when defining a dynamic schema. |
profileRequired |
Boolean | Optional | Use true if users should be able to map profile attributes from Experience Platform to custom attributes on your destination platform. |
segmentRequired |
Boolean | Required | This parameter is required by Destination SDK and should always be set to true . |
identityRequired |
Boolean | Required | Set to true if users should be able to map identity types from Experience Platform to the attributes you defined in the profileFields array . |
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.
The following combinations of required mappings are currently supported:
Configuring a required source field only is currently not supported.
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.
The example below shows both required source and destination mappings. When both source and destination fields are specified as required mappings, users cannot select or edit any of the two fields, and can only view the predefined selection.
"schemaConfig": {
"requiredMappingsOnly": true,
"requiredMappings": [
{
"sourceType": "text/x.schema-path",
"source": "personalEmail.address",
"destination": "personalEmail.address"
}
]
}
Parameter | Type | Required/Optional | Description |
---|---|---|---|
requiredMappingsOnly |
Boolean | Optional | When this is set to true , users cannot map other attributes and identities in the activation flow, apart from the required mappings that you define in the requiredMappings array. |
requiredMappings.sourceType |
String | Required | Indicates the type of the source field. Supported values:
|
requiredMappings.source |
String | Required | Indicates the value of the source field. Supported value types:
|
requiredMappings.destination |
String | Required | Indicates the value of the target field. When both source and destination fields are specified as required mappings, users cannot select or edit any of the two fields and can only view the selection. |
As a result, both the Source field and Target field sections in the Platform UI are greyed out.
The example below shows a required destination mapping. If only the destination field is specified as required, users can select what source field to map to it.
"schemaConfig": {
"requiredMappingsOnly": true,
"requiredMappings": [
{
"destination": "identityMap.ExamplePartner_ID",
"mandatoryRequired": true,
"primaryKeyRequired": true
}
]
}
Parameter | Type | Required/Optional | Description |
---|---|---|---|
requiredMappingsOnly |
Boolean | Optional | When this is set to true , users cannot map other attributes and identities in the activation flow, apart from the required mappings that you define in the requiredMappings array. |
requiredMappings.destination |
String | Required | Indicates the value of the target field. When only the destination field is specified, users can select a source field to map to the destination. |
mandatoryRequired |
Boolean | Optional | Indicates whether the mapping should be marked as a mandatory attribute. |
primaryKeyRequired |
Boolean | Optional | Indicates whether the mapping should be marked as a deduplication key. |
As a result, the Target field section in the Platform UI is greyed out, while the Source field section is active and users can interact with it. The Mandatory key and Deduplication key options are active, and users cannot change them.
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.
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: