How do I create a derived property type?

Providing you have suitable access control permissions, you can create a derived property type to define the core characteristics of derived properties of that type, in particular the entity type to which they belong and the derivation formula. See how to create a standard 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 derived property type specifies:

• A 3-stage key (for example, Instrument/Derived/Domicile) used to retrieve derived properties for entities, where:
  • The first stage is the domain and determines the entity type to which derived properties belong, in this case instruments.
  • The second stage is the scope (or namespace); this can be used to partition derived properties, and/or entitle them so only people with suitable permissions can see them.
  • The third stage is the code; this must be unique within the scope.
• A data type. This should be one of the primitive data types string, number, boolean or date.
• A derivation formula that instructs LUSID how to automatically calculate derived property values.

There are several ways to create a derived property type:

• Using the LUSID REST API
• Using the LUSID web app
• If you have a Luminesce license, by writing a SQL query.

Note: Once you have created a derived property type, you can use the UpdateDerivedPropertyDefinition API to change most characteristics, including the derivation formula, though not the scope and code.

Using the LUSID REST API

1. Obtain an API access token.
2. Call the LUSID CreateDerivedPropertyDefinition 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 derived properties belong (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.
   • A scope of system and a code of either string, number, boolean or date.
   • A derivationFormula that performs one or more operations on one or more existing data fields or properties.

For example, to create a derived property type with a 3-stage key of Instrument/Derived/Domicile that normalises countries to a standard set of codes:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions/derived"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json"
  -d '{
    "domain": "Instrument",
    "scope": "Derived",
    "code": "Domicile",
    "displayName": "Instrument domicile",
    "dataTypeId": {"scope": "system", "code": "string"},
    "propertyDescription": "Normalising domicile-related data for instruments",
    "derivationFormula": "map(coalesce(Properties[Instrument/VendorA/country_issue], Properties[Instrument/VendorB/origin], 'Unknown'):
      'United Kingdom'='UK', 'united_kingdom'='UK',
      'Great Britain'='UK', 'GB'='UK', 'DE'='Germany',
      'United States'='USA', 'usa'='USA', default='Unknown')"
}'

Providing the request is successful, the response confirms the 3-stage key (highlighted in red):

{
  "key": "Instrument/Derived/Domicile",
  "valueType": "String",
  "displayName": "Instrument domicile",
  "dataTypeId": {
    "scope": "system",
    "code": "string"
  },
  "type": "Label",
  "unitSchema": "NoUnits",
  "domain": "Instrument",
  "scope": "Derived",
  "code": "Domicile",
  "valueRequired": false,
  "lifeTime": "Perpetual",
  "propertyDefinitionType": "DerivedDefinition",
  "propertyDescription": "Normalising domicile-related data for instruments",
  "derivationFormula": "Map(coalesce(Properties[Instrument/VendorA/country_issue], Properties[Instrument/VendorB/origin], 'Unknown'): 'United Kingdom' = 'UK', 'united_kingdom' = 'UK', 'Great Britain' = 'UK', 'GB' = 'UK', 'DE' = 'Germany', 'United States' = 'USA', 'usa' = 'USA', default = 'Unknown')",
  ...
}

You can now retrieve instruments from LUSID with their derived properties, at which point LUSID automatically calculates derived property 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 Derived property.
6. Select a Data type of either String[system], Number[system], Boolean[system] or Date[system].
7. Specify a Derivation formula:
   
8. Click the Create button to create the derived property type. You can now retrieve instruments from LUSID with their derived properties, at which point LUSID automatically calculates derived property values.