How do I create a property type?

Providing you have suitable access control permissions, you can create a property type to define core characteristics for all the properties of that type, in particular the entity type to which they must be added. See how to create a derived property type.

Note: Once you have created a property type, you can use the UpdatePropertyDefinition API, but only to update certain non-essential characteristics such as description. If you need to change core characteristics you must call the DeletePropertyDefinition API and start again.

A property type defines:

  • A 3-stage key (for example, Instrument/BBG/AnalystRating) that is used both to add properties to entities and retrieve them from it, where:

    • The first stage is the domain and determines the entity type to which properties belong and must be added, in this case instruments.

    • The second stage is the scope (or namespace); this can be used to partition properties from different sources, and/or entitle properties so only people with suitable permissions can see and change them. For example, you could store Bloomberg ratings in Instrument/BBG/AnalystRating and Refinitiv Datascope ratings in Instrument/Refinitiv/AnalystRating, and add both to instruments (perhaps with different permissions).

    • The third stage is the code; this must be unique within the scope.

  • A data type. This can either be a primitive type such as string, number, boolean or date, or a complex type that can function to restrict the allowed values for a property, so for example the built-in rating data type only allows values of the form AAA, AA, BB and so on. Note you can create your own custom data type if no suitable built-in type exists. Note also that multi-value properties must be string.

  • Whether properties are single or multi-value. For example, a SocialSecurityNumber property would be single-value. An EmailAddress property, however, could be multi-value.

  • Whether single-value properties must be created as metric values or label values when adding properties to entities.

  • Whether properties are time-variant or perpetual. For example, an Address property could have different values during different time periods. A DateOfBirth property, however, would have a value that is effective for all time. Note some entity types such as portfolios and instruments support time-variant properties; others such as transactions and holdings do not.

There are several ways to create a property type:

Using the LUSID REST API

This section explains how to create a single-value property type (constraintStyle of Property). For information on creating:

To do this:

  1. Obtain an API access token.

  2. Call the LUSID CreatePropertyDefinition API for your LUSID domain, passing in your API access token and specifying in the request body:

    • A domain that corresponds to the entity type to which properties must be added (see a complete list), for example Instrument.

    • A scope that is unique within the domain. This value is case-sensitive.

    • A code that is unique within the scope. This value is case-sensitive.

    • A user-friendly displayName.

    • The scope and code of a built-in data type or a custom data type.

    • For entity types that support time-variant properties, a lifeTime of TimeVariant to specify that property values can vary during different time periods. The default is Perpetual.

    • A constraintStyle of Property to mandate single-value.

For example, to create a time-variant single-value property type with a 3-stage key of Instrument/BBG/AnalystRating and using the built-in rating data type to constrain allowed values and maintain data quality:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json-patch+json"
  -d '{
    "domain": "Instrument",
    "scope": "BBG",
    "code": "AnalystRating",
    "displayName": "Analyst Rating",
    "dataTypeId": {"scope": "system", "code": "rating"},
    "lifeTime": "TimeVariant",
    "constraintStyle": "Property",
    "propertyDescription": "Analyst ratings from Bloomberg for instruments"
  }'

Providing the request is successful, the response confirms:

  • The 3-stage property key

  • Whether property values must be created as metric values or label values (in this case label values):

{
 "key": "Instrument/BBG/AnalystRating",
 "valueType": "String",
 "displayName": "Analyst Rating",
 "dataTypeId": {
   "scope": "system",
   "code": "rating"
 },
 "type": "Label",
 "unitSchema": "NoUnits",
 "domain": "Instrument",
 "scope": "BBG",
 "code": "AnalystRating",
 "valueRequired": false,
 "lifeTime": "TimeVariant",
 "constraintStyle": "Property,
 "propertyDefinitionType": "ValueProperty",
 "propertyDescription": "Analyst ratings from Bloomberg for instruments",
 ...
}

You can now add properties of this type to entities of the prescribed type and specify values.

Using the LUSID web app

  1. Sign in to the LUSID web app using the credentials of a LUSID administrator.

  2. From the top left menu, select Data Management > Properties.

  3. Click the Create Property button (top right).

  4. Fill out all the fields on the Basic data screen of the Create Property dialog:
     

  5. On the Property screen of the dialog, choose:

    • Value Property to create single-value properties. You can choose any Data type from the dropdown.

    • Multi Value Property to create multi-value properties. The Data type is restricted to String [system]. 

    • For entity types that support time-variant properties, a lifeTime of TimeVariant to specify that property values can vary during different time periods. Otherwise, Perpetual:
       

  6. Click the Create button to create the property type. You can now add properties of this type to entities of the prescribed type and specify property values.