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:

{
  "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 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:

{
  "call_to_action_type": "icon",
  "call_to_action": "globe"
}

Example definition for a URL property with a text button:

{
  "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:

{
  "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:

{
  "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:

{
  "enable_interactivity": true
}

System

Computed

Has a SQL query to compute the value.

type: computed

Example definition for an “Open PR count” property:

{
  "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.

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:

{
  "rule_type": "regex",
  "file_path": "path/to/SPECIAL_FILE.md",
  "match_expression": "^#.*?Special Section$"
}

See the Advanced properties page for more information on setting up rules and writing scorecard checks.

This is a system property — values are computed by DX from repository file contents and cannot be set via the API.

Compatibility between property edits

Entity 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

{
  "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"
  }
}