--- title: "Property" canonical_url: "https://docs.getdx.com/webapi/types/property/" md_url: "https://docs.getdx.com/webapi/types/property.md" last_updated: "2026-05-19" --- # Property A property is a fact about each entity that belongs to an entity type. The property is configured on the entity type, then values for that property are configured for each entity. ## Example This is a multi-select property defining the languages used in a service: ```json { "type": "multi_select", "identifier": "language", "name": "Language", "description": "Languages used by the service", "visibility": "visible", "ordering": 0, "definition": { "options": [ { "value": "Ruby", "color": "#fb923c" }, { "value": "HTML", "color": "#fb923c" }, { "value": "Shell", "color": "#fb923c" } ] } } ``` ## Fields | Key | Type | Required? | Description | | ------------- | ------------------------- | --------- | -------------------------------------------------------------------------------------------------- | | `type` | string | Yes | The type of the property. See below for supported types. | | `identifier` | string | Yes | The user-defined unique identifier for the property. | | `name` | string | Yes | The human-readable name of the property. | | `description` | string | | The description of the property. | | `visibility` | `'visible'` \| `'hidden'` | | Whether the property is visible by default or hidden by default. | | `ordering` | integer | | The ordering of this property, relative to other visible or hidden properties for the entity type. | | `definition` | varies | Yes | Object specifying type-specific information for this type. See below for details. | ## Additional optional fields when updating properties | Key | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `on_definition_conflict` | object | How to resolve conflicts when a property definition changes. See the [compatibility](#compatibility-between-property-edits) section for details. | ## Supported property types ### Single field #### URL A string which is a URL. `type`: `url` `definition` fields: | Field | Type | Required? | Description | | --------------------- | ------ | --------- | ---------------------------------------------------------------------------- | | `call_to_action_type` | string | Yes | How the URL is presented. Either `"icon"` or `"text"`. | | `call_to_action` | string | Yes | The icon name (when `call_to_action_type` is `"icon"`) or button label text. | Example `definition` for a URL property with an icon button: ```json { "call_to_action_type": "icon", "call_to_action": "globe" } ``` Example `definition` for a URL property with a text button: ```json { "call_to_action_type": "text", "call_to_action": "Visit site" } ``` #### Text Simple open-ended text value. `type`: `text` `definition`: `{}` #### Boolean Simple true/false value. `type`: `boolean` `definition`: `{}` #### Number Simple integer value. `type`: `number` `definition`: `{}` #### Date A string which is a date. `type`: `date` `definition`: `{}` ### Multiple fields #### Single-select Has a distinct set of possible values. One value allowed. `type`: `select` Example `definition` for a "Service tier" property: ```json { "options": [ { "value": "Tier-1", "color": "#ef4444" }, { "value": "Tier-2", "color": "#fbbf24" }, { "value": "Tier-3", "color": "#38bdf8" } ] } ``` #### Multi-select Has a distinct set of possible values. Multiple values allowed. `type`: `multi_select` Example `definition` for a "Language" property: ```json { "options": [ { "value": "Ruby", "color": "#ef4444" }, { "value": "Javascript", "color": "#fbbf24" }, { "value": "Python", "color": "#818cf8" }, { "value": "Java", "color": "#4ade80" }, { "value": "Go", "color": "#38bdf8" } ] } ``` #### List An ordered list of string values. Unlike multi-select, list values are free-form and not constrained to a predefined set of options. `type`: `list` `definition`: `{}` #### JSON A nested json object. `type`: `json` `definition`: `{}` ### Communication #### User A string which is a user's email address. `type`: `user` `definition`: `{}` #### Email An email address used as a notification destination for entity-level alerts. `type`: `email` `definition`: `{}` > **Note:** This property type is only available if your account has email notifications configured. #### Slack Channel A Slack channel used as a notification destination for entity-level alerts. `type`: `slack_channel` `definition`: `{}` The value is an object with the following fields: | Field | Type | Description | | -------------- | ------ | -------------------------------- | | `channel_id` | string | The Slack channel ID. | | `channel_name` | string | The human-readable channel name. | > **Note:** This property type is only available if your account has a Slack integration configured. #### Microsoft Teams Channel A Microsoft Teams channel used as a notification destination for entity-level alerts. `type`: `msteams_channel` `definition`: `{}` The value is an object with the following fields: | Field | Type | Description | | -------------- | ------ | -------------------------------- | | `channel_id` | string | The Microsoft Teams channel ID. | | `channel_name` | string | The human-readable channel name. | > **Note:** This property type is only available if your account has a Microsoft Teams integration configured. #### OpenAPI Spec A JSON object containing an OpenAPI or Swagger spec. `type`: `openapi` `definition` fields: | Field | Type | Required? | Description | | ---------------------- | ------- | --------- | ---------------------------------------------------------------- | | `enable_interactivity` | boolean | Yes | Whether to render an interactive API explorer for this property. | Example `definition`: ```json { "enable_interactivity": true } ``` ### System #### Computed Has a SQL query to compute the value. `type`: `computed` Example `definition` for an "Open PR count" property: ```json { "sql": "SELECT \n dce.public_id AS entity_public_id,\n dce.name AS entity_name,\n dce.identifier AS entity_identifier,\n COUNT(gp.id) FILTER (WHERE gp.merged IS NULL AND gp.closed IS NULL) AS output\nFROM dx_catalog_entities dce\nLEFT JOIN dx_catalog_entity_aliases dcea ON dce.id = dcea.entity_id\nLEFT JOIN dx_catalog_entity_alias_entries dceae ON dcea.id = dceae.entity_alias_id\nLEFT JOIN repos r ON dceae.identifier = r.external_id\nLEFT JOIN github_repositories gr ON gr.source_id::text = r.external_id\nLEFT JOIN github_pulls gp ON gr.id = gp.repository_id\nWHERE dce.identifier = $entity_identifier\nGROUP BY dce.id, dce.name, dce.identifier\nORDER BY dce.name", "output_type": "number", "output_aggregation": "sum" } ``` #### File matching rule Reads file contents from a connected repository and extracts pattern matches. Requires a [Repository Integration](https://docs.getdx.com/catalog/overview#repository-integrations). `type`: `file_matching_rule` `definition` fields: | Field | Type | Description | | ------------------ | ------ | ------------------------------------------------------------- | | `rule_type` | string | The matching strategy: `file_exists`, `substring`, or `regex` | | `file_path` | string | The static path to the file within the repository | | `match_expression` | string | The substring or regular expression to match against | Example `definition`: ```json { "rule_type": "regex", "file_path": "path/to/SPECIAL_FILE.md", "match_expression": "^#.*?Special Section$" } ``` See the [Advanced properties](https://docs.getdx.com/catalog/advanced-properties/#file-matching-rules) page for more information on setting up rules and writing scorecard checks. This is a [system property](https://docs.getdx.com/catalog/advanced-properties/#system-properties) — values are computed by DX from repository file contents and cannot be set via the API. ## Compatibility between property edits [Entity properties](https://docs.getdx.com/webapi/types/properties/) are validated whenever entities are created, updated, or upserted. Validation also occurs when a property's _definition_ changes. If a definition changes in a way that introduces conflicts - for example, removing a select option when entities are currently using that option - the caller can decide how to handle the conflict. The following actions can be taken. | Action | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `abort` | The default action. If an update to a property will cause a conflict, the response will fail with HTTP status `409 Conflict`. | | `remove_values` | Remove any values in the Catalog that contain the deleted option(s). | | `change_values` | Update any values in the Catalog that contain the deleted option(s) by changing them to a new value, specified by a `new_value` field. The new value must be contained in the list of options. | ### Example usage ```json { "type": "multi_select", "identifier": "language", "name": "Language", "description": "Languages used by the service", "visibility": "visible", "ordering": 0, "definition": { "options": [ { "value": "Ruby", "color": "#fb923c" }, { "value": "HTML", "color": "#fb923c" }, // Suppose we remove `Bash` and replace it with `Shell`... // { "value": "Bash", "color": "#fb923c" } { "value": "Shell", "color": "#fb923c" } ] }, "on_definition_conflict": { // We will migrate all the `Bash` entity properties to `Shell`. "action": "change_values", "new_value": "Shell" } } ``` --- ## Sitemap [Overview of all docs pages](/llms.txt)