Reference data model overview

Version: 10.4

This topic describes the model that is used when reading and writing data to the Reference Data Service. Refer to the Reference Data Client API for complete code samples.

Types

Definition types are identified by a unique string name such as “Sitecore XP Automation Plan”, “Sitecore XP Goal”, or “Airport Code”. Definition types are strings, not custom classes.

In the example below, a definition type named “Airport Code” is being retrieved. If the definition type does not exist, the .EnsureDefinitionTypeAsync() method creates it:

RequestResponse

var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

DefinitionTypeKey definitionType = await client.EnsureDefinitionTypeAsync("Airport Code");

Monikers

Definitions within the reference data service are identified by a string identifier called a moniker. A moniker is unique within a given definition type, meaning that it is possible to use the same moniker for two different definition types.

The following example demonstrates how to create a definition with the moniker “LHR” of type “Airport Codes”:

RequestResponse

var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

DefinitionTypeKey definitionType = await client.EnsureDefinitionTypeAsync("Airport Codes");

var definitionKey = new Sitecore.Xdb.ReferenceData.Model.DefinitionKey("LHR", definitionType, 1);

Definition data

Reference data definitions are defined through 2 DTO types. One class defines the attributes common across all languages for the definition and the other defines the cultural specific attributes of the definition. These types are provided as type parameters to the Definition<TCommon,TCulture> class, where TCommonData and TCultureData can be a simple type such as string or a custom type.

In the following example, a new instance of Definition<string,string> is instantiated with a definition key and a culture-specific entry is added:

RequestResponse

var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

DefinitionTypeKey definitionType = await client.EnsureDefinitionTypeAsync("Airport Codes");

var definitionKey = new Sitecore.Xdb.ReferenceData.Model.DefinitionKey("LHR", definitionType, 1);

var definition = new Sitecore.Xdb.ReferenceData.Model.Definition<string, string>(definitionKey);

definition.CultureData[new CultureInfo("en")] = "London Heathrow Airport";

Culture-specific data and common data

The reference data service supports culture-specific and common data. Culture-specific data includes names and descriptions, and common data includes anything that is the same across cultures - such as a value. In the following example, common data is populated and two culture-specific entries (for en and dk) are added:

RequestResponse

var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;

DefinitionTypeKey definitionType = await client.EnsureDefinitionTypeAsync("Airport Codes");

var definitionKey = new Sitecore.Xdb.ReferenceData.Model.DefinitionKey("LHR", definitionType, 1);

var definition = new Sitecore.Xdb.ReferenceData.Model.Definition<string, string>(definitionKey)
{
    IsActive = true,  // Denotes that this version is active (version 1)
    CommonData = "Common data about this airport code",
            CultureData = {
                    { new CultureInfo("en"), "London Heathrow Airport" },
                    { new CultureInfo("dk"), "Danish London Heathrow Airport" }
            }
};

Culture-invariant data

In some cases, there will be data to display but the culture of the data is not specified - particularly when the data has come from an external data provider. For example, a GeoIP data provider will provide the names of cities where an IP is located. The city names will be in English. However, they do not explicitly specify that the names will be in English, so this fact cannot be assumed. In such cases, you should store the data as culture invariant.

Note

Culture invariant data can be used as a fallback mechanism if a specific culture is not available.

Store culture-invariant data

The following examples show two ways of storing culture-invariant data:

RequestResponse

definition.CultureData[CultureInfo.InvariantCulture] = "Swedenland";
definition.CultureData[new CultureInfo("")] = "Swedenland";

Get culture-invariant data

If you do not specify a culture when retrieving a definition, all available cultures will be returned. If you only want to see culture-invariant data, pass CultureInfo.Invariant as the Culture on the DefinitionCriteria:

RequestResponse

DefinitionCriteria criteria = new DefinitionCriteria("moniker", definitionTypeKey)
{
    Culture = CultureInfo.InvariantCulture
};

Once the definition has been returned, you can get the culture-invariant data as follows:

RequestResponse

var data = definition.CultureData[CultureInfo.InvariantCulture];

Versions

Definitions are versioned by number. Individual versions can be made active or inactive. When deleting definitions, you must delete all versions of the definition individually. A definition version can only be deleted if it has been marked as inactive.

Note

This operation is intentionally laborious to ensure developers do not accidentally delete definitions.

Do you have some feedback for us?

If you have suggestions for improving this article,