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: {}
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_identifierand returns anoutputcolumn. 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 anentity_identifiercolumn along with theoutputcolumn, 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"
}
}