Schema

A schema is a JSON file that tells Data 360 what events to expect and what fields each event contains. Every eventType value used in your sitemap must have a matching event definition in the schema. Every field sent in an event payload must have a corresponding field definition in that event’s schema entry.

[ACTION REQUIRED: Review Note] - WARNING: Once a schema is uploaded and a Data Stream is created against it, no changes can be made to existing event types or fields. You can only add new ones. Finalise and validate your schema thoroughly before uploading.

Schema Structure

A schema file is a JSON object with a records array. Each item in the array defines one eventType and includes:

developerName — The internal identifier for the eventType. Must exactly match the eventType value used in the sitemap (case-sensitive).
masterLabel — A human-readable display name shown in the Data 360 UI.
category — Either Engagement or Profile. Engagement events capture user interactions; Profile events capture identity and attribute data.
externalDataTranFields — An array of field definitions for this eventType. Each field has a masterLabel, developerName, dataType and isDataRequired flag.

Certain fields are required in every schema record regardless of eventType. The SDK sets these automatically — you do not need to populate them in the sitemap — but they must be declared in the externalDataTranFields array of every record. The Field developerName below must be created for the corresponding EventLogs Property that appeared in the browser console event logs (“Events translated for Data Cloud”) from the previous step.

EventLogs Property	Field developerName	Data Type	Description
`category`	`category`	Text	Required. Whether the event is `Engagement` or `Profile`.
`dateTime`	`dateTime`	DateTime	Required. Format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. Used for data partitioning on Engagement events.
`deviceId`	`deviceId`	Text	Required. Primary key for Profile events.
`eventId`	`eventId`	Text	Required. Primary key for Engagement events.
`eventType`	`eventType`	Text	Required. The event type name — matches the `developerName` of the schema entry for this event.
`sessionId`	`sessionId`	Text	Required. Identifies the current user session.
`interactionName`	`interactionName`	Text	Required. A descriptive name for the interaction, set in the sitemap.
`pageView`	`pageView`	Number	`1` (page load) or `0` (user interaction). Set by the SDK based on how the event fired.
`sourceChannel`	`sourceChannel`	Text	The SDK channel that collected the event. Always `Web`.
`sourceLocale`	`sourceLocale`	Text	The locale of the page, e.g. `en_US` or `de_DE`.
`sourcePageType`	`sourcePageType`	Text	The `name` of the page type configuration that triggered the event.
`sourceUrl`	`sourceUrl`	Text	The URL of the page the event was sent from.
`sourceUrlReferrer`	`sourceUrlReferrer`	Text	The previously visited URL. Only the domain is included.

Creating the Schema

Create a new file named schema.json.
Add the top-level structure with a records array.
For each eventType value used in your sitemap, add a record object to the array with the correct masterLabel, developerName, and category.
For Profile events (e.g., contactPointEmail, identity, partyIdentification), set category to "Profile". For all interaction events, set category to "Engagement".
Inside each record, add an externalDataTranFields array. Add a field definition for each required field listed in the table above, using the Data Type shown and setting "isDataRequired": true for all. On the eventId field for Engagement events (or deviceId for Profile events), also set "primaryIndexOrder": 1.
For each custom field that the specific eventType captures, add an additional field definition with masterLabel, developerName, dataType (Text, Number, or DateTime), and isDataRequired (true or false) as appropriate.

Example Schema

{
  "records": [
    {
      "masterLabel": "WebEngagement",
      "developerName": "userEngagement",
      "category": "Engagement",
      "externalDataTranFields": [
        {
          "masterLabel": "category",
          "developerName": "category",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "dateTime",
          "developerName": "dateTime",
          "dataType": "DateTime",
          "isDataRequired": true
        },
        {
          "masterLabel": "deviceId",
          "developerName": "deviceId",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "eventId",
          "developerName": "eventId",
          "dataType": "Text",
          "isDataRequired": true,
          "primaryIndexOrder": 1
        },
        {
          "masterLabel": "eventType",
          "developerName": "eventType",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "interactionName",
          "developerName": "interactionName",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "sessionId",
          "developerName": "sessionId",
          "dataType": "Text",
          "isDataRequired": true
        }
      ]
    },
    {
      "masterLabel": "Identity",
      "developerName": "identity",
      "category": "Profile",
      "externalDataTranFields": [
        {
          "masterLabel": "category",
          "developerName": "category",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "dateTime",
          "developerName": "dateTime",
          "dataType": "DateTime",
          "isDataRequired": true
        },
        {
          "masterLabel": "deviceId",
          "developerName": "deviceId",
          "dataType": "Text",
          "isDataRequired": true,
          "primaryIndexOrder": 1
        },
        {
          "masterLabel": "eventId",
          "developerName": "eventId",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "eventType",
          "developerName": "eventType",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "sessionId",
          "developerName": "sessionId",
          "dataType": "Text",
          "isDataRequired": true
        },
        {
          "masterLabel": "email",
          "developerName": "email",
          "dataType": "Text",
          "isDataRequired": false
        },
        {
          "masterLabel": "firstName",
          "developerName": "firstName",
          "dataType": "Text",
          "isDataRequired": false
        },
        {
          "masterLabel": "lastName",
          "developerName": "lastName",
          "dataType": "Text",
          "isDataRequired": false
        }
      ]
    }
  ]
}

[ACTION REQUIRED: Review Note] - NOTE: A default schema file covering the most common event types is available to download — Salesforce Recommended Schema. You can use this as a starting point and extend it with any custom event types your sitemap requires.

Validation Checklist

Before uploading the schema, cross-reference it against your event logs from the browser console. Check the following for every event type:

Required fields — Any field that is marked as "isDataRequired": true in the schema must also appear with a value in the event logs.
Field data types match — Confirm that the data type of each field value in the event logs matches the dataType defined in the schema. For example, a field defined as Number must not be arriving as a string.
eventType matches developerName — The eventType value in the event logs must exactly match the developerName of the corresponding schema entry. This is case-sensitive.
Category is correctly set — Interaction events should use "Engagement". Events that capture identity or user attributes should use "Profile".
Schema structure is valid JSON — Validate the file using a JSON linter before uploading. A malformed JSON file will fail silently or produce unexpected ingestion errors.

[ACTION REQUIRED: Update Image Here] - Original Context/URL: Screenshot of browser console showing “Events translated for Data Cloud” logs with Profile and Engagement arrays, used to cross-reference against schema field definitions.

Uploading the Schema

Go to Data 360 Setup and click Web & Mobile Apps.
Click on the connector you created in the previous step.
In the Schema block, click Upload Files and select your schema.json file.
Review the schema preview — verify Event Category, Field data types, Primary Key, and Required columns match what you defined.
Compare the preview against your schema.json file to confirm accuracy.
Click Save.

[ACTION REQUIRED: Update Image Here] - Original Context/URL: Screenshot of the Schema block on the connector page showing the upload button and schema preview panel.

[ACTION REQUIRED: Review Note] - WARNING: Once the schema is saved and a Data Stream is created against it, event types and fields cannot be removed or modified — only new ones can be added. If a mistake is found after a Data Stream exists, a new connector and schema must be created from scratch.

Summary

With the schema uploaded, every event type your sitemap sends has a matching definition in Data 360. Proceed to create a Data Stream to begin ingesting events into Data Lake Objects.

Previous Next