Views:

1. Introduction

Properties can be used to extend LUSID's data model, allowing you to attach additional information to those entities in LUSID that support properties. See the current list.

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

Note: LUSID stores your custom properties but does not use them in calculation or other business operations. However, LUSID does have a number of system properties that can be used to access system information not available by other mechanisms.

2. Property Definition

Every property must have a property definition 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 labelmetric, 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 bitemporal 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. For more information on this and some examples, including how to retrieve property values as a time series in order to better understand how information has changed over time, see this article.

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

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

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