Check

The definition for a single check contained in a Scorecard.

Example

{
  "id": "y3ynphtim18c",
  "ordering": 5,
  "name": "Has Dockerfile",
  "description": "Service has a valid Dockerfile for containerization",
  "sql": "select 'PASS' as status",
  "filter_sql": "select ce.identifier\nfrom dx_catalog_entities ce\njoin dx_catalog_entity_types cet on cet.id = ce.entity_type_id\njoin dx_catalog_properties cp on cp.entity_type_id = cet.id and cp.identifier = 'cluster'\njoin dx_catalog_entity_properties cep on cep.entity_id = ce.id\nwhere cet.identifier = 'service';",
  "filter_message": "This check only applies to services with a `cluster` property defined",
  "output_enabled": true,
  "output_type": "custom",
  "output_custom_options": {
    "unit": "container",
    "decimals": 0
  },
  "output_aggregation": "mean",
  "aggregate_thresholds": {
    "lower": 25,
    "upper": 75,
    "colors": ["red", "yellow", "green"]
  },
  "estimated_dev_days": 1.5,
  "external_url": "https://docs.company.com/docker-guide",
  "published": true,
  "level": {
    "id": "vic57y3o11r4",
    "name": "Bronze"
  }
}

Properties

Key Type Description
id string The check’s unique ID.
ordering number The ordering of this check within its container Level or Check Group.
name string The check’s name.
description string The check’s plain text description.
sql string The query to execute in order to determine whether an entity is passing or failing. For more information, see Writing Scorecard Checks.
filter_sql string | null Optional SQL query that filters the relevant entities that this check will apply to. Must return an identifier column.
filter_message string | null If filter_sql is being applied, this message will show when viewing details for a check result.
output_enabled boolean Whether to display a formatted value on a check result instead of a simple pass/warn/fail icon.
output_type string | null The output formatting to apply. Only present when output_enabled is true. See available output types.
output_custom_options Output Custom Options | null Additional formatting configuration for the custom output type. See below for details.
output_aggregation string | null When viewing the Checks Report grouped by team, this defines how to combine the output values of each check result. Available values are mean, sum, count, min, max, and median. Only applicable when output_enabled is true and output_type is a numeric type (i.e. any type other than string, json, or list).
aggregate_thresholds Aggregate Thresholds Thresholds used to color-code the aggregated score shown in the Checks Report when results are grouped by team or another property. See below for details.
estimated_dev_days number | null Provides an estimate to entity owners about how long it will take to get a check passing for a single entity. Every check in an initiative must specify this.
external_url string | null The check’s external URL, used for documentation or other instructions for passing the check.
published boolean Whether this check is published or is still a draft. Draft checks do not impact an entity’s level or points.
level object For level-based scorecards, this lists the id and name of the Level under which this check is nested.
check_group object For points-based scorecards, this lists the id and name of the Check Group under which this check is nested.

Additional properties required in a request body

These properties define the Level or Check Group under which a check should be nested.

Key Type Description
scorecard_level_key string Required for level-based scorecards. The user-defined key of the level under which this check should be nested.
scorecard_check_group_key string Required for points-based scorecards. The user-defined key of the check group under which this check should be nested.

Output Custom Options

Key Type Description
unit string The unit to show to the right of the value. Will be pluralized when shown in the UI. For example, a unit of widget will display as 1 widget or 2 widgets.
decimals “auto” | number Decimal precision for the value. A string value of “auto” will show the default amount of precision for a number provided by the check’s SQL result set, whether an integer (e.g. 123) or a floating point number (e.g. 0.333333). A numeric value will set fixed precision at that many digits. For example, decimals: 2 will result in formatted values like 1.21 Jigawatts or 2.00 widgets.

Aggregate Thresholds

Defines the boundaries and colors used to color-code the aggregated score for this check in the Checks Report when results are grouped by team, owner, or another property. If not configured, defaults to { "lower": 25, "upper": 75, "colors": ["red", "yellow", "green"] }. For more details, see Set thresholds for aggregate scores.

Key Type Description
lower number The lower boundary of the threshold range. If output isn’t enabled (or its output type isn’t numeric), this is a percentage (0–100) of entities passing. Otherwise, it’s a raw aggregated output value.
upper number The upper boundary of the threshold range. Must be greater than lower. Uses the same units as lower.
colors array of strings The three colors applied below lower, between lower and upper, and above upper, respectively. Each value must be one of red, yellow, or green.