--- title: "How do I create a property type?" slug: "how-do-i-create-a-property-type" tags: ["property definition", "property type", "3-stage key"] updated: 2025-09-27T10:15:22Z published: 2025-09-27T10:15:22Z canonical: "support.lusid.com/how-do-i-create-a-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 property type? You can create a *property type* to define core characteristics for all the properties of that type, in particular the [entity type](/v1/docs/what-is-an-entity) to which they must be added. [See how to create a derived property type](/v1/docs/how-do-i-create-a-derived-property-type). > **Note**: Once you have created a property type, you can use the [UpdatePropertyDefinition](https://www.lusid.com/docs/api#operation/UpdatePropertyDefinition) API, but only to update certain non-essential characteristics such as description. If you need to change core characteristics you must call the [DeletePropertyDefinition](https://www.lusid.com/docs/api#operation/DeletePropertyDefinition) API and start again. A property type defines: - A 3-stage key (for example, `Instrument/BBG/AnalystRating`) that is used both to add properties to entities and retrieve them from it, where: - The first stage is the *domain* and determines the entity type to which properties belong and must be added, in this case instruments. - The second stage is the *scope* (or namespace); this can be used to partition properties from different sources, and/or entitle properties so only people with suitable permissions can see and change them. For example, you could store Bloomberg ratings in `Instrument/BBG/AnalystRating` and Refinitiv Datascope ratings in `Instrument/Refinitiv/AnalystRating`, and add both to instruments (perhaps with different permissions). - The third stage is the *code*; this must be unique within the scope. [Allowed values in 3-stage keys](/v1/docs/lusid-api-requests-character-limits-and-allowed-values). - A [data type](/v1/docs/what-is-a-data-type). This can either be a primitive type such as `string`, `number`, `boolean` or `date`, or a complex type that can function to restrict the allowed values for a property, so for example the built-in `rating` data type only allows values of the form AAA, AA, BB and so on. Note you can [create your own custom data type](/v1/docs/how-do-i-create-a-custom-data-type-and-store-reference-data) if no suitable built-in type exists. Note also that multi-value properties must be `string`. - Whether properties are single or [multi-value](/v1/docs/understanding-multi-value-properties). For example, a `SocialSecurityNumber` property would be single-value. An `EmailAddress` property, however, could be multi-value. - Whether single-value properties must be created as [metric values or label values](/v1/docs/label-values-and-metric-values) when adding properties to entities. - Whether properties are [time-variant or perpetual](/v1/docs/understanding-perpetual-and-time-variant-properties). For example, an `Address` property could have different values during different time periods. A `DateOfBirth` property, however, would have a value that is effective for all time. Note some entity types such as portfolios and instruments support time-variant properties; others such as transactions and holdings do not. ## Using the LUSID REST API This section explains how to create a single-value property type (`constraintStyle` of `Property`). For information on creating: - A multi-value property type (`constraintStyle` of `Collection`), see [this article](/v1/docs/understanding-multi-value-properties). - The special use case of an identifier (`constraintStyle` of `Identifier`), see the article for [person entities](/v1/docs/representing-people-in-lusid-using-person-entities), [legal entities](/v1/docs/representing-institutions-in-lusid-using-legal-entities) or [custom entities](/v1/docs/extending-lusids-data-model-using-custom-entities). To do this, call the LUSID [CreatePropertyDefinition](https://www.lusid.com/docs/api#operation/CreatePropertyDefinition) API and specify in the request body: - A `domain` that corresponds to the entity type to which properties must be added ([see a complete list](https://www.lusid.com/docs/api#operation/CreatePropertyDefinition)), 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`. - The `scope` and `code` of a [built-in data type](/v1/docs/what-is-a-data-type) or a [custom data type](/v1/docs/how-do-i-create-a-custom-data-type-and-store-reference-data). - For entity types that [support time-variant properties](/v1/docs/what-is-bitemporal-data#understanding-perpetual-and-time-variant-data-items), a `lifeTime` of `TimeVariant` to specify that property values can vary during different time periods. The default is `Perpetual`. - A `constraintStyle` of `Property` to mandate single-value. For example, to create a time-variant single-value property type with a 3-stage key of `Instrument/BBG/AnalystRating` and using the built-in `rating` data type to constrain allowed values and maintain data quality: ```json curl -X POST "https://.lusid.com/api/api/propertydefinitions"  -H "Authorization: Bearer "  -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"  }' ``` Providing the request is successful, the response confirms: - The 3-stage property key - Whether property values must be created as metric values or label values (in this case label values): ```json { "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", ... } ``` You can now [add properties of this type to entities](/v1/docs/how-do-i-add-a-property-to-an-entity) of the prescribed type and specify 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/5fd96181-6db4-4440-944c-2192646453f6.png?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A09Z&se=2026-11-04T02%3A47%3A09Z&sr=c&sp=r&sig=GRzbgeRzuOpIGahgQcYQMpSB8vKsO41HrVS%2BAZams2E%3D) 5. On the **Property** screen of the dialog, choose: - **Value Property** to create single-value properties. You can choose any **Data type** from the dropdown. - **Multi Value Property** to create multi-value properties. The **Data type** is restricted to `String [system]`. - For entity types that [support time-variant properties](/v1/docs/what-is-bitemporal-data#understanding-perpetual-and-time-variant-data-items), a `lifeTime` of `TimeVariant` to specify that property values can vary during different time periods. Otherwise, `Perpetual`: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/a7453496-c398-45e4-bc6f-7c4845648ce5.png?sv=2026-02-06&spr=https&st=2026-11-04T01%3A47%3A09Z&se=2026-11-04T02%3A47%3A09Z&sr=c&sp=r&sig=GRzbgeRzuOpIGahgQcYQMpSB8vKsO41HrVS%2BAZams2E%3D) 6. Click the **Create** button to create the property type. You can now [add properties of this type to entities](/v1/docs/how-do-i-add-a-property-to-an-entity) of the prescribed type and specify property values.