How do I create a property type?

  • Updated on Aug 30, 2024
  • Published on Aug 19, 2024

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:

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"
  }'
JSON

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",
 ...
}
JSON

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

  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.