Skip to main content

DecisionExplanation

Explains a specific decision result for an entity at a given timestamp.

Returned by POST /decisions/explain. Fully deterministic given (condition_id, condition_version, entity, timestamp). Application context has zero influence on decision, parameter values, or attribution weights (see guardrails.md §2.5).

Naming alignment (from API spec x-ts-note): DecisionResult.value ← the decision output in evaluation results DecisionExplanation.decision ← the same concept in explain responses These use different field names by spec design — do not rename either.

threshold_applied: present for threshold/percentile/change/z_score. Null for equals (no numeric parameter) and composite (operator, not threshold). label_matched: present for equals only. Null for all boolean strategies.

condition_idCondition Id (string)required
condition_versionCondition Version (string)required
entityEntity (string)required
timestamp objectrequired
anyOf
string<date-time>
decision objectrequired
anyOf
boolean
decision_typeDecisionType (string)required

Output type of a condition evaluation.

boolean — produced by threshold, percentile, z_score, change, composite categorical — produced by equals only

Possible values: [boolean, categorical]

concept_value objectrequired
anyOf
number
strategy_typeStrategyType (string)required

Canonical strategy type identifiers. String values are the wire values.

Critical spellings (from py-instructions.md — these are non-obvious): Z_SCORE = 'z_score' NOT 'zscore' — used everywhere: API, YAML, guardrails

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

threshold_applied object
anyOf
number
label_matched object
anyOf
string
drivers object[]
  • Array [
    • signalSignal (string)required
    contributionContribution (number)required
    value objectrequired
    anyOf
    number
  • ]
    • DecisionExplanation
    {
      "condition_id": "string",
      "condition_version": "string",
      "entity": "string",
      "timestamp": "2024-07-29T15:51:28.071Z",
      "decision": true,
      "decision_type": "boolean",
      "concept_value": 0,
      "strategy_type": "threshold",
      "threshold_applied": 0,
      "label_matched": "string",
      "drivers": [
        {
          "signal": "string",
          "contribution": 0,
          "value": 0
        }
      ]
    }