---
title: "What is a derived property?"
slug: "what-is-a-derived-property"
tags: ["replace", "average", "properties", "string mapping", "coalesce", "mathematical operation", "grammer", "data model", "if condition", "derivationFormula", "property definition", "numeric mapping", "derived property", "derived property definition", "concatenation", "derivation formula"]
updated: 2026-03-02T11:49:43Z
published: 2026-03-02T11:49:43Z
canonical: "support.lusid.com/what-is-a-derived-property"
---

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

# What is a derived property?

A derived property is a special kind of [property](/v1/docs/properties) whose values derive from one or more data fields or other properties, using a mathematical, mapping or similar operation. [Current restrictions and limitations](/v1/docs/what-is-a-derived-property#restrictions-and-limitations-of-derived-properties).

Unlike standard properties, you do not explicitly add derived properties to entities and specify values. Rather, LUSID automatically calculates values when you choose to [retrieve entities with their derived properties](/v1/docs/how-do-i-retrieve-a-property-or-derived-property-for-an-entity).

You can use derived properties to curate a 'golden source' representation of your data. Consider the following example, of instruments loaded into LUSID from two different data vendors. Data relating to domicile from each vendor has been mapped to two (standard) properties, represented by the **country_issue** and **origin** columns. We can see that the same countries are represented using different values, and that some values are missing:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/6a220895-27e2-47a3-ae11-f4c1308a157c.png)

Because it seems likely this information has the same meaning, we can create a **Domicile** derived property that automatically maps and coalesces **country_issue** and **origin** values to a new, normalised set. This derived property can subsequently be used for reporting purposes, or for consumption by a downstream system, without our having altered the original data:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/68af3555-f75b-4fcc-84f0-f262695ef14c.png)

## Working with derived properties

1. The first step is to [construct a derivation formula](/v1/docs/derivation-formulas-part-1-operations-and-allowed-values). For example, the **Domicile** derived property above might have a formula that uses the `map` and `coalesce` operations like this:

```json
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')
```

For information on syntax, available operations, and which data fields and properties you can derive from, see [this article](/v1/docs/derivation-formulas-part-1-operations-and-allowed-values).
2. The next step is to [create a derived property type](/v1/docs/how-do-i-create-a-derived-property-type) that stores the derivation formula and defines other characteristics such as the entity type to which derived properties belong.
3. The final step is to cause LUSID to automatically calculate derived property values by [retrieving entities with their derived properties](/v1/docs/how-do-i-retrieve-a-property-or-derived-property-for-an-entity).
4. If required, you can [audit how LUSID](/v1/docs/understanding-how-lusid-calculates-derived-property-values) has calculated a particular derived property value.

## Restrictions and limitations of derived properties

1. Not all types of entity support derived properties. For example, custom entities, portfolio groups, and [OMS](/v1/docs/compliance-order-management-system-oms)-related entities (placements, blocks, executions and so on) do not support derived properties. [See the last column in this table](/v1/docs/what-is-an-entity).
2. A derived property in a domain (ie. `Holding`) can have a [formula](/v1/docs/derivation-formulas-part-1-operations-and-allowed-values) that derives from any other property in the `Holding` domain (including other derived properties), but it is not guaranteed to be able to derive from all stored holding fields, nor can it necessarily derive from properties, fields, identifiers or similar components from other types of entity. [See these tables](/v1/docs/derivation-formulas-part-2-entity-components).
  1. In particular, note a derived property in the `Instrument` domain cannot have a formula that derives from fields in the nested economic definition of instruments.
3. A derivation formula cannot be longer than 8000 characters.
4. A derived property cannot be multi-value.
5. A derived property in the `Instrument` domain can be retrieved for (that is, decorated onto) holdings and transactions, but it is not otherwise possible to retrieve derived properties across domains [in the same way as standard properties](/v1/docs/retrieving-properties-from-the-domains-of-other-types-of-entity).