--- title: "How do I create a derived property type?" slug: "how-do-i-create-a-derived-property-type" tags: ["derived property definition", "derived property type", "3-stage key"] updated: 2025-07-24T10:35:22Z published: 2025-07-24T10:35:22Z canonical: "support.lusid.com/how-do-i-create-a-derived-property-type" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I create a derived property type? You can create a *derived property type* to define the core characteristics of [derived properties](/v1/docs/what-is-a-derived-property) of that type, in particular the entity type to which they belong and the derivation formula. [See how to create a standard property type](/v1/docs/how-do-i-create-a-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. Note this is currently restricted to: `Instrument`, `Portfolio`, `Transaction`, `Holding`, `Person` and `LegalEntity`, plus a special case of `DerivedValuation` for [custom metrics](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#belonging-to-the-special-derivedvaluation-domain). - 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](/v1/docs/derivation-formulas-part-1-operations-and-allowed-values) 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`. - Whether derived property values are [filterable](/v1/docs/filtering-information-retrieved-from-lusid) as part of a request to retrieve information from LUSID. By default filtering is disabled, since there are performance implications. You can enable filtering for a maximum of 500 derived property types in total. > **Note**: Once created, you can use the [UpdateDerivedPropertyDefinition](https://www.lusid.com/docs/api#operation/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. ## Using the LUSID REST API Call the LUSID [CreateDerivedPropertyDefinition](https://www.lusid.com/docs/api#operation/CreateDerivedPropertyDefinition) API and specify in the request body: - A `domain` that corresponds to the entity type to which derived properties belong, 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. - Set `isFilterable` to `true` to enable filtering for derived property values of this type. For example, to create a filterable derived property type with a 3-stage key of `Instrument/Derived/Domicile` that normalises countries to a standard set of codes: ```json curl -X POST "'://.lusid.com/api/api/propertydefinitions/derived'   -H 'Authorization: Bearer '   -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",    "isFilterable": true,     "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): ```json {   "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')",  "isFilterable": true,  ... } ``` You can now retrieve instruments from LUSID with their derived properties, at which point LUSID automatically calculates derived property values. ## Using Luminesce You can use the [Lusid.Property.Definition.Writer](/v1/docs/lusidpropertydefinitionwriter) provider. ## Using the LUSID web app 1. Sign in to the [LUSID web app](https://www.lusid.com/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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/f2fbc03e-a669-49c5-9951-ddfe2d33f41c.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A14%3A18Z&se=2026-11-09T07%3A14%3A18Z&sr=c&sp=r&sig=DPlshbvdmBvRnpqmOci1jRlsafXq8H2HGvsSk7SHbiQ%3D) 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/80554278-d7fb-4c01-a9a9-a50b809086c0.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A14%3A18Z&se=2026-11-09T07%3A14%3A18Z&sr=c&sp=r&sig=DPlshbvdmBvRnpqmOci1jRlsafXq8H2HGvsSk7SHbiQ%3D) 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.