The xConnect collection model

Current version: 9.3

The collection model defines the CLR types, facets, and events that make up the structure of experience data. Sitecore ships with a default collection model that defines facets such as PersonalInformation and event types such as Goal and Outcome. You can define any number of additional models with your own facets and events.

All models are defined entirely in code. The following model defines one contact facet and one event:

using System;
using Sitecore.XConnect.Operations;
using Sitecore.XConnect.Schema;

namespace Sitecore.XConnect.Sample.Model
    public static class CollectionModel
        public static XdbModel Model { get; } = BuildModel();

        static XdbModel BuildModel()
            var builder = new XdbModelBuilder("Sitecore.XConnect.Sample.Model", new XdbModelVersion(1, 0));

            //Contact facets
            builder.DefineFacet<Contact, CustomFacet>(FacetKeys.CustomFacetKey);

            // Events

            return builder.BuildModel();

    public static class FacetKeys
        public const string CustomFacetKey = nameof(CollectionModel.Avatar);

In the context of a console application, the xConnect Client API can be initialized with the custom model:

var cfg = new XConnectClientConfiguration(
    new XdbRuntimeModel(CollectionModel.Model), collectionClient, searchClient, configurationClient);

Alternatively, the custom model can be added to configuration in Sitecore. When the application starts, a runtime model is assembled from all models listed in configuration and is available when you request the xConnect client:

using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
    // Core collection model and custom model both available from configuration

The xConnect service must have a JSON representation of any model that a client application wishes to use:

Tools exist to serialize the model into JSON. The JSON and C# versions of a model must match, otherwise the xConnect Client API will fail to initialize. xConnect only needs the JSON representation of a model - there is no need to deploy DLLs.

Do you have some feedback for us?

If you have suggestions for improving this article,