Related resources:




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 attached. See how to create a derived property type.

Note: If you are the LUSID domain owner, you are automatically assigned the built-in lusid-administrator role, which has all the permissions necessary to perform the operations in this article.

A property type specifies:

  • A 3-stage key (for example, Instrument/BBG/AnalystRating) that is used both to attach properties to entities and retrieve them from it, where:
    • The first stage is the domain and determines the entity type to which properties must be attached, 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 attach 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 can have multiple values of not. 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 attaching 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 of time.

Note: A property type is one of the few data structures in LUSID that is monotemporal. That is, the definition can be updated, and you can retrieve previous definitions by rolling back the as at timeline. However, for a given as at datetime, the prevailing definition will apply to all effective at datetimes.

There are several ways to create a 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.


  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:
    • domain that corresponds to the entity type to which properties must be attached (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.
    • A lifeTime of TimeVariant to determine that property values can vary during different time periods. The default is Perpetual.
    • A constraintStyle of Collection to determine that properties can have multiple values. The default is Property, which means single-value. Note the Identifier allowed value is reserved for a special use case with person entities, legal entities and custom entities.

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>"
-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 (highlighted in red)
  • Whether property values must be created as metric values or label values (in this case label values, highlighted in yellow):
 "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 attach 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]
    • Life time of TimeVariant or Perpetual:
  6. Click the Create button to create the property type. You can now attach properties of this type to entities of the prescribed type and specify property values.