Label values and metric values

When you attach a single-value property to an entity you must create it as either a label value or a metric value. This is determined by the underlying data type of the property type.

When you create a property type, you specify a data type that can either be:

A primitive built-in data type such as string, number, boolean or date.
A complex built-in data type such as rating or currencyAndAmount.
A custom data type you create yourself.

Each data type has an underlying value type that automatically determines whether property values must be created as label values or metric values.

Creating a property type that mandates label values

The following property type request uses the built-in complex data type rating:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json-patch+json"
  -d '{
   "domain": "Instrument",
   "scope": "BBG",
   "code": "AnalystRating",
   "displayName": "Analyst Rating",
   "dataTypeId": {"scope": "system", "code": "rating"},
   "lifeTime": "TimeVariant",
   "constraintStyle": "Property",
   "propertyDescription": "Analyst ratings from Bloomberg for instruments"
  }'

In the response, LUSID confirms that property values must be created as label values:

{
  "key": "Instrument/BBG/AnalystRating",
  "valueType": "String",
  "displayName": "Analyst Rating",
  "dataTypeId": {
    "scope": "system",
    "code": "rating"
  },
  "type": "Label",
  "unitSchema": "NoUnits",
  "domain": "Instrument",
  "scope": "BBG",
  "code": "AnalystRating",
  "valueRequired": false,
  "lifeTime": "TimeVariant",
  "constraintStyle": "Property",
  "propertyDefinitionType": "ValueProperty",
  "propertyDescription": "Analyst ratings from Bloomberg for instruments",
   ...
}

Creating a property type that mandates metric values

The following property type request uses the built-in complex data type currencyAndAmount:

curl -X POST "https://<your-domain>.lusid.com/api/api/propertydefinitions"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json-patch+json"
  -d '{
   "domain": "Transaction",
   "scope": "Ibor",
   "code": "Fee",
   "displayName": "Broker fee",
   "dataTypeId": {"scope": "system", "code": "currencyAndAmount"},
   "lifeTime": "Perpetual",
   "constraintStyle": "Property",
   "propertyDescription": "Fee paid to broker"
}'

In the response, LUSID confirms that property values must be created as metric values, and in addition specifies a unit schema of Iso4217Currency:

{
  "key": "Transaction/Ibor/Fee",
  "valueType": "Decimal",
  "displayName": "Broker fee",
  "dataTypeId": {
    "scope": "system",
    "code": "currencyAndAmount"
  },
  "type": "Metric",
  "unitSchema": "Iso4217Currency",
  "domain": "Transaction",
  "scope": "Ibor",
  "code": "Fee",
  "valueRequired": false,
  "lifeTime": "Perpetual",
  "constraintStyle": "Property",
  "propertyDefinitionType": "ValueProperty",
  "propertyDescription": "Fee paid to broker",
  ...
}

The Iso4217Currency unit schema mandates that when you attach a property to an entity the metricValue object must have a unit that is a valid ISO 4127 country code specified as a string, for example:

"properties": {
  "Transaction/Ibor/Fee": {
    "key": "Transaction/Ibor/Fee",
    "value": {
      "metricValue": {
        "value": 30,
        "unit": "GBP"
      }
    }
  }
}

Note it is possible for a metric value to have a unit schema of Basic or NoUnits, in which case there is no need to specify a unit for a metricValue object; it can be left empty or omitted:

"properties": [
  {
    "key": "Instrument/Ibor/ReplacementCost",
    "value": {
      "metricValue": {
        "value": 15,
        "unit": ""
      }
    }
  }
]