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.

Property Definition

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

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 two types: either a label or a metric.

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 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.

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.

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.