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

Boolean

Simple true/false value.

type: boolean

definition: {}

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

Number

Simple integer value.

type: number

definition: {}

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

Text

Simple open-ended text value.

type: text

definition: {}

URL

A string which is a URL.

type: url

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 an icon button:

{
  "call_to_action_type": "icon",
  "call_to_action": "Visit site"
}

Date

A string which is a date.

type: date

definition: {}

JSON

A nested json object.

type: json

definition: {}

OpenAPI Spec

A JSON object containing an OpenAPI or Swagger spec.

type: openapi

definition: {}

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