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

An integer or decimal number 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 JSON object or array.

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

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.
channel_link string A slack:// deep link to the channel. Generated automatically.

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.
channel_link string A link that opens the channel in Microsoft Teams. Generated automatically.

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

definition fields:

Field Type Required? Description
sql string Yes The SQL query used to compute the value. Use $entity_identifier to reference a single entity, or $entity_identifiers to compute values for a batch of entities. See the SQL formats below.
output_type string Yes The data type of the computed output.
output_aggregation string How values are combined when rolled up across entities (for example, by domain or owner team). Only applies to numeric output types.

The output_type and output_aggregation fields support the same values as the Check object type, except that custom is not a valid output_type for computed properties.

The sql field accepts one of two SQL formats:

  • Single-entity — uses $entity_identifier and returns an output column. Only the first row is kept. Can also use other single-entity query variables, such as $entity_github_repo_ids.
  • Batch — uses $entity_identifiers, which expands to a comma-separated list of quoted identifiers (for example, 'service-a','service-b'), and returns an entity_identifier column along with the output column, with exactly one row per entity. Batch properties can compute much faster than single-entity properties because they run far fewer queries.

Batch queries must use $entity_identifiers on its own: it can’t be combined with other variables, and $entity_identifier and $entity_identifiers can’t be used in the same query. See Computed properties for more batch examples.

Example single-entity definition for an “Owner count” property:

{
  "sql": "SELECT COUNT(o.entity_id) AS output\nFROM dx_catalog_entities e\nLEFT JOIN dx_catalog_entity_owners o ON e.id = o.entity_id\nWHERE e.identifier = $entity_identifier",
  "output_type": "number",
  "output_aggregation": "sum"
}

Example batch definition for the same property:

{
  "sql": "SELECT e.identifier AS entity_identifier, COUNT(o.entity_id) AS output\nFROM dx_catalog_entities e\nLEFT JOIN dx_catalog_entity_owners o ON e.id = o.entity_id\nWHERE e.identifier IN ($entity_identifiers)\nGROUP BY e.identifier",
  "output_type": "number",
  "output_aggregation": "sum"
}

This is a system property — values are computed by DX using the property’s SQL query and cannot be set via the API.

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 Required? Description
rule_type string Yes The matching strategy: file_exists, substring, or regex
file_path string Yes The static path to the file within the repository
match_expression string Yes (except when rule_type is file_exists) The substring or regular expression to match against

Read more about file matching rule configuration.

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