---
title: "Including properties and derived properties in valuation reports"
slug: "including-properties-and-derived-properties-in-valuation-reports"
updated: 2026-03-13T14:14:18Z
published: 2026-03-13T14:14:18Z
canonical: "support.lusid.com/including-properties-and-derived-properties-in-valuation-reports"
---

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

# Including properties and derived properties in valuation reports

You can include properties in a valuation report to supplement the many hundreds of LUSID [metrics](/v1/docs/what-is-a-metric). These can be:

- Standard [custom properties](/v1/docs/properties) you have created yourself to extend the data model, belonging to either:
  - Instruments being valued, or to entities whose property domains are accessible to instruments; namely, transactions, holdings, portfolios and portfolio groups. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#including-standard-properties-in-valuation-reports).
  - Entities explicitly related to instruments being valued. Instruments can have relationships with legal entities, persons, portfolios, portfolio groups and custom entities. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#belonging-to-entities-related-to-instruments-being-valued).
- [Derived properties](/v1/docs/what-is-a-derived-property) whose values are calculated on-the-fly from other properties or from entity fields or other data sources, belonging to either:
  - Instruments being valued or to holdings. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#including-derived-properties-in-valuation-reports).
  - The special `DerivedValuation` property domain, designed to enable you to create custom metrics. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#belonging-to-the-special-derivedvaluation-domain).
- [System properties](/v1/docs/what-is-a-system-property) provided by LUSID. These properties can belong to instruments being valued, or to entities whose property domains are accessible to instruments; namely, transactions, holdings, portfolios and portfolio groups. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#including-system-properties-in-valuation-reports).

| Entity type | Standard properties | Derived properties | System properties |
| --- | --- | --- | --- |
| Instrument | ✅ | ✅ | ✅ |
| Transaction | ✅(if registered as [SHK](/v1/docs/what-is-a-sub-holding-key-shk)) | ❌ | ✅ (if registered as [SHK](/v1/docs/what-is-a-sub-holding-key-shk)) |
| Holding | ✅ | ✅ | ✅ |
| Portfolio | ✅ | ❌ | ✅ |
| Portfolio group | ✅ | ❌ | ✅ |
| Legal entity | ✅ (if related to instruments) | ❌ | ❌ |
| Person | ✅ (if related to instruments) | ❌ | ❌ |
| `DerivedValuation`* | N/A | ✅ | N/A |

* This is not a type of entity, but rather a standalone property domain.

## Including standard properties in valuation reports

### Belonging to instruments being valued, or to entities with accessible property domains

You can include these properties using the same syntax as metrics, for example:

```json
"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/BBG/Country", "op": "Value"}             # Property
  {"key": "Transaction/SHK/Strategy", "op": "Value"}           # Property
]
```

### Belonging to entities related to instruments being valued

You can include properties from [related entities](/v1/docs/creating-relationships-between-certain-types-of-entity) using a special syntax. Note the following:

- The [property type](/v1/docs/how-do-i-create-a-property-type) cannot have a `constraintStyle` of `Identifier`.
- The [relationship type](https://support.lusid.com/v1/docs/creating-relationships-between-certain-types-of-entity#creating-a-relationship-type) must have the instrument as the `sourceEntityType` and the related entity as the `targetEntityType`. The cardinality must be `ManyToOne`.
- You cannot include system properties from related entities.

For example, imagine instruments are related to legal entities representing issuing organisations, each of which has a `LegalEntity/Scores/DEIScore` custom property. To include the DEI scores of related legal entities in a valuation report, specify the 3-stage key in the normal way and additionally use the `options` field to specify the scope and code of the relationship type between instrument and legal entity as key/value pairs:

```json
"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                       # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                         # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                  # Metric
  {"key": "LegalEntity/Scores/DEIScore", "op": "Value", "options": {     # Property from related legal entities
    "RelationshipDefinitionIdScope": "InstrumentIssuer",
    "RelationshipDefinitionIdCode": "IssuerId",
    }
  }
]
```

Note the API response returns an array in case the related property is multi-value. If there is more than one value, note the LUSID web app only displays the first:

```json
"data": [
  {
    "Valuation/EffectiveAt": "2023-07-10T00:00:00.0000000+00:00",
    "Holding/Cost/Pfolio": 500,
    "Valuation/PvInPortfolioCcy": 1000,
    "LegalEntity/Scores/DEIScore(
       RelationshipDefinitionIdScope=\"InstrumentIssuer\", 
       RelationshipDefinitionIdCode=\"IssuerId\")": 
        [
          87, 79, 65
        ],
    ...
```

## Including derived properties in valuation reports

### Belonging to instruments being valued or to holdings

You can include these derived properties using the same syntax as metrics, for example:

```json
"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/MyDerivedProps/Region", "op": "Value"}   # Derived property
  {"key": "Holding/MyDerivedProps/Lineage", "op": "Value"}     # Derived property
]
```

### Belonging to the special `DerivedValuation` domain

A derived property in the `DerivedValuation` domain defines a custom metric.

For example, you could [create a derived property type](/v1/docs/how-do-i-create-a-derived-property-type) for a `DerivedValuation/MyDerivedProps/AdjustedExposure` custom metric with a derivation formula as follows:

```json
{
  "domain": "DerivedValuation",
  "scope": "MyDerivedProps",
  "code": "AdjustedExposure",
  "displayName": "Adjusted Exposure",
  "dataTypeId": {"scope": "system", "code": "number"},
  "propertyDescription": "Exposure adjusted by a haircut factor stored as an instrument property",
  "derivationFormula": "AddressKeys[Valuation/InstrumentExposureInPortfolioCcy] * Properties[Instrument/MyStandardProps/Haircut]"
}
```

For more information on the LUSID metrics, properties and entity fields you can use in the derivation formula for a custom metric, see [this table](/v1/docs/derivation-formulas-part-2-entity-components#custom-valuation-metric-derived-properties).

Note you can use the `Valuation/EffectiveAt` LUSID metric to reference the valuation date and perform [date operations](/v1/docs/derivation-formulas-part-1-operations-and-allowed-values#date-operations) in the formula, for example:

```json
"derivationFormula": "if(AddressKeys[Valuation/EffectiveAt] gt Properties[Instrument/OTC/StartDate]) then Addresskeys[Valuation/PV] else 0"
```

You can include a custom metric in a valuation report using the same syntax as a LUSID metric, for example:

```json
"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},                              # LUSID metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},                                # LUSID metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},                         # LUSID metric
  {"key": "DerivedValuation/MyDerivedProps/AdjustedExposure", "op": "Value"}    # Custom metric
]
```

## Including system properties in valuation reports

You can include system properties using the same syntax as metrics, for example:

```json
"metrics": [
  {"key": "Valuation/EffectiveAt", "op": "Value"},             # Metric
  {"key": "Holding/Cost/Pfolio", "op": "Value"},               # Metric
  {"key": "Valuation/PvInPortfolioCcy", "op": "Value"},        # Metric
  {"key": "Instrument/default/Name", "op": "Value"}            # System property
  {"key": "Holding/default/TaxlotId", "op": "Value"}           # System property
]
```