How do I create a derived property type?

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.

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 derivation formula that instructs LUSID how to automatically calculate derived property values.

  • A data type that matches the data returned by the derivation formula. This should be one of the primitive data types string, number, boolean or date.

Note: Once created, you can use the UpdateDerivedPropertyDefinition API to change most characteristics. Be aware that if you change the derivation formula you may also need to change the data type to match.

Call the LUSID CreateDerivedPropertyDefinition API and specify in the request body:

  • 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')"
}'
JSON

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')",
  ...
}
JSON

You can now retrieve instruments from LUSID with their derived properties, at which point LUSID automatically calculates derived property values.

You can use the Lusid.Property.Definition.Writer provider.

  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.