---
title: "Including properties and derived properties in valuation reports"
slug: "including-properties-and-derived-properties-in-valuation-reports"
tags: ["valuation", "property", "metric", "related entity", "relationship"]
updated: 2026-10-20T10:57:30Z
published: 2026-10-20T10:57:30Z
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:

- [Custom properties](/v1/docs/properties) and/or [system properties](/v1/docs/what-is-a-system-property) belonging to either:
  - Instruments being valued, or to entities whose property domains are accessible to instruments; see the table below. [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 help you create custom metrics. [More information](/v1/docs/including-properties-and-derived-properties-in-valuation-reports#belonging-to-the-special-derivedvaluation-domain).

| Entity type | Custom properties | System properties | Derived properties |
| --- | --- | --- | --- |
| Instrument | ✅ | ✅ | ✅ |
| Transaction | ✅(if registered as [SHK](/v1/docs/what-is-a-sub-holding-key-shk)) | ✅ (if registered as SHK) | ❌ |
| Custodian account | ✅ | ✅ | ❌ |
| 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 properties in valuation reports

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

You can include properties using the syntax `<entity>/Properties[<domain>/<scope>/<code>]`, 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/Properties[Instrument/BBG/Country]", "op": "Value"}       # Custom property
  {"key": "Transaction/Properties[Transaction/SHK/Strategy]", "op": "Value"}    # Custom property
  {"key": "Holding/Properties[Holding/default/TaxlotId]", "op": "Value"}        # System 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, use the syntax `<entity>/Properties[<domain>/<scope>/<code>]`, and additionally set the `options` [field](/v1/docs/setting-options-on-metrics) 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/Properties[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/Properties[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 derived properties using the syntax `<entity>/Properties[<domain>/<scope>/<code>]`, 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/Properties[Instrument/MyDerivedProps/Region]", "op": "Value"}   # Derived property
  {"key": "Holding/Properties[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
]
```