What are properties?

Learn how to use properties to associate additional information against entities in LUSID

Introduction

Properties can be used to extend LUSID's data model, allowing you to attach additional information to the following entities in LUSID: portfolios, portfolio groups, instruments and transactions.

For example, you could define a 'Portfolio Manager' property for your portfolios, or an 'Asset Class' property for instruments.

LUSID has a number of predefined properties, but you are able to create your own as well.

Property Definition

Every new property must be defined before it can be used. To define a new property you must supply the following information:

Property Key

The Property Key uniquely identifies a property, and comprises of 3 values:

  • Domain: what kind of entity this property can be associated with (e.g. 'Portfolio' or 'Instrument').
  • Scope: used to logically separate properties - for instance you may wish to separate particular special fields as pertaining just to one prime broker.
  • Code: a short text value used to identify the property within its scope

Commonly, property keys are represented in the form "{domain}/{scope}/{code}", e.g. "Transaction/primeBrokerA/specialTradedCode".

Property Type

Each property must fall in to one of three types: a label, metric, or label set.

A label property is a piece of text data, and can be used to group data during an aggregation operation, or decorated on to tables of results.

A label set property is a set of multiple text labels that can be attached to an entity object.

A metric property comprises of a decimal value and an associated unit. These can be used in calculations during aggregation, or decorated on to tables of results.

Data Type

Data types are used to constrain the values of the property, to help maintain data quality. They are used to validate property data when it is loaded, and to provide details on how best to display the values when they are returned.

LUSID has a number of built-in data types, including simple primitive types like strings (text), dates or numbers. It also supports more complex data types such as currency (3-letter ISO currency codes).

Property Lifetime

As LUSID is a bi-temporal system, properties can be defined as being either time-variant or perpetual. This indicates whether a property value is expected to change over time, or whether a given value should be valid 'forever'.

An example of a time-variant property would be 'portfolio manager', as it may change during the lifetime of a portfolio. When a time-variant property's value is changed, it must be associated with an effective date.

Please note: The effective date of a time-variant property must be greater than or equal to the effective creation date of the entity that it is associated with (e.g in the portfolio manager example above, your property would need to post-date the creation date of the portfolio). 

Conversely, an example of a perpetual property might be the 'trading venue' for a trade. This value is determined at the point of doing the transaction, and can never change thereafter. As such, perpetual property values have no effective date - they are considered to be effective always.

Note this doesn't prevent you from correcting bad data in LUSID. You can still overwrite any property value, and LUSID will maintain a full audit history, which can be observed by altering the as-at time for the request.

 If this field not defined when defining a new property, property lifetime will default to perpetual.

Property Constraint Style

Property constraint styles define the uniqueness and cardinality of a property value for a given entity object type. We support the below value(s):

  • Property: Each entity object can only have at most one value for such property at any given AsAt and EffectiveAt times. Entity objects of the same type can have the same property value. An example would be credit rating of a financial instrument.
  • Collection: Each entity object can have zero or more string values for such property at any given AsAt and EffectiveAt time. In this case supply a PropertyValue of type LabelValueSet.

 If this field not defined when defining a new property, constraint style will default to property.

Using Properties

Once a property is defined, you can use it via its property key. You set property values against entities, and can request that property values are decorated onto results obtained from the API.