ConditionDefinition

A registered, versioned condition definition.

Stored in the definitions table with definition_type='condition'. The body JSONB column holds the serialisation of this model.

Immutability: once registered, a (condition_id, version) pair is permanent. Updates require a new version. The unique constraint on the definitions table enforces this at the DB level.

Deprecation: deprecated conditions are retained for audit. All existing task references continue to resolve. deprecated=True is advisory — the runtime does not automatically reject deprecated conditions, but the rebinding validation step warns when a task is being rebound to a deprecated condition version.

condition_idCondition Id (string)required

versionVersion (string)required

concept_idConcept Id (string)required

concept_versionConcept Version (string)required

strategy objectrequired

typerequired

Possible values: [change, composite, equals, percentile, threshold, z_score]

change

params objectrequired

change strategy parameters.

direction: 'increase' | 'decrease' | 'any' value: percentage change threshold (must be >= 0) window: lookback duration string (default '1d')

Note: parameter key is 'value' (not 'threshold' or 'cutoff').

directionChangeDirection (string)required

Possible values: [increase, decrease, any]

valueValue (number)required

Possible values: >= 0

windowWindow (string)

Default value: 1d

composite

params objectrequired

composite strategy parameters.

operator: 'AND' | 'OR' operands: list of condition_ids to evaluate (minimum 2)

Compiler enforcement rules (checked at compile time, not here):

• all operands must produce decision — equals is excluded
• composite cannot be nested inside another composite's operands
• all operand condition_ids must exist in the registry

Minimum 2 operands is enforced here at model construction time.

operatorCompositeOperator (string)required

Possible values: [AND, OR]

operandsstring[]required

Possible values: >= 2

equals

params objectrequired

equals strategy parameters.

value: the label to match labels: optional closed set of valid labels (subset of the categorical type's declared label set). When provided, 'value' must be a member of this list. Validated at compile time against the concept's declared categorical labels.

Calibration note: equals has no numeric parameter to adjust. POST /conditions/calibrate always returns no_recommendation with reason='not_applicable_strategy' for conditions using this strategy.

valueValue (string)required

labels object

anyOf

• string[]
• null

Array [

string

]

percentile

params objectrequired

percentile strategy parameters.

direction: 'top' | 'bottom' (NOT 'above'/'below') value: percentile cutoff in range [0, 100]

directionPercentileDirection (string)required

top / bottom — NOT above / below (a common source of bugs).

Possible values: [top, bottom]

valueValue (number)required

Possible values: >= 0 and <= 100

threshold

params objectrequired

threshold strategy parameters.

direction: 'above' | 'below' value: the fixed cutoff (any float — no global bounds)

Note: parameter key is 'value', NOT 'cutoff'. Fires when: direction='above' → concept_value > value direction='below' → concept_value < value

directionThresholdDirection (string)required

Possible values: [above, below]

valueValue (number)required

z_score

params objectrequired

z_score strategy parameters.

threshold: number of standard deviations required to trigger (must be > 0) direction: 'above' | 'below' | 'any' window: lookback duration string (default '30d')

Note: parameter key is 'threshold', NOT 'value' or 'cutoff'. This is different from every other strategy — z_score is the only one where the sensitivity param is called 'threshold'.

thresholdThreshold (number)required

Possible values: > 0

directionZScoreDirection (string)required

Possible values: [above, below, any]

windowWindow (string)

Default value: 30d

namespaceNamespace (string)required

Possible values: [personal, team, org, global]

created_at object

anyOf

• string<date-time>
• null

string<date-time>

deprecatedDeprecated (boolean)

Default value: false

ConditionDefinition

{
  "condition_id": "string",
  "version": "string",
  "concept_id": "string",
  "concept_version": "string",
  "strategy": {
    "type": "threshold",
    "params": {
      "direction": "above",
      "value": 0
    }
  },
  "namespace": "personal",
  "created_at": "2024-07-29T15:51:28.071Z",
  "deprecated": false
}