---
title: CascadeDefinition schema
description: "A cascade's node graph: an ordered array of CascadeNode objects. Exactly one ApplicantSource node is the entry point; every other node is reached through…"
canonical_url: "https://cascades.crscreditapi.com/docs/api/schemas/CascadeDefinition"
doc_version: "1.0.0"
last_updated: "2026-10-09T18:04:24Z"
source: "public/api-docs/v1/swagger.yaml#/components/schemas/CascadeDefinition"
---

# CascadeDefinition

A cascade's node graph: an ordered array of `CascadeNode` objects.
Exactly one `ApplicantSource` node is the entry point; every other
node is reached through the edge keys (`next_step`, `pass_steps`,
`human_review_steps`, `fail_steps`), each of which is an array of
node `id`s that must resolve within the same array. An empty array
is accepted on create/update (an empty draft) but cannot be run.

Defined in [openapi.json](https://cascades.crscreditapi.com/openapi.json#/components/schemas/CascadeDefinition) ([YAML](https://cascades.crscreditapi.com/openapi.yaml)).

| Field | Type | Required | Description |
|---|---|---|---|
| `[]` | CascadeNode | no | One node of a cascade. `id` and `type` are always required; the remaining required keys depend on `type` (see `x-required-keys-by-type`): \| type \| required keys \| purpose \| \|---\|---\|---\| \| `ApplicantSource` \| — \| Entry point; exposes the trigger payload as `context.applicant`. Exactly one per cascade. \| \| `BillingProduct` (alias `Product`) \| `billing_product_code` \| Pulls a report (credit, criminal, eviction, identity, income). \| \| `IfElse` (alias `Condition`) \| `branches` \| Evaluates conditions and routes to `pass_steps`, `human_review_steps` or `fail_steps`. \| \| `Wait` \| `wait` \| Pauses for `wait.duration` × `wait.unit`. \| \| `GoTo` \| `target_step` \| Runtime jump to another node (not a graph edge). \| \| `ShowResults` \| — \| Terminal node that surfaces collected outputs. \| \| `Action` \| `action_type` \| `Approve`, `SendEmail` (reads `email`), `AdverseAction` (reads `adverse_action`), `InternalNotification` (reads `internal_notification`). \| `Product` and `Condition` are legacy aliases the engine still resolves; new definitions should use `BillingProduct` and `IfElse`. Unknown keys are tolerated and ignored by the engine. |
|   `id` | string | yes | Unique within the definition, e.g. `step_credit`. Edge keys reference nodes by this value. |
|   `type` | string | yes |  One of: `"ApplicantSource"`, `"BillingProduct"`, `"Product"`, `"IfElse"`, `"Condition"`, `"Wait"`, `"GoTo"`, `"ShowResults"`, `"Action"`. |
|   `name` | string | no | Human-readable label shown in the builder and in `step_outputs`. |
|   `next_step` | array of string | no | Default forward edge — ids of the node(s) to run next. |
|   `billing_product_code` | string | no | `BillingProduct` / `Product` only. The product to pull, e.g. `EQF1003` (Equifax credit), `TUC1001` (TransUnion credit), `CIC4002` (criminal), `CIC4003` (eviction). May also be nested as `config.billing_product_code`. |
|   `config` | object | no | Optional per-node configuration. `store_result_as` names the key under which a product's output is stored. |
|     `store_result_as` | string | no |  |
|     `billing_product_code` | string | no | Alternative location for `billing_product_code`. |
|   `branches` | object | no | `IfElse` / `Condition` only. Conditions for the `pass` branch and (optionally) the `human_review` branch; anything that matches neither takes `fail_steps`. |
|     `pass` | CascadeBranch | no | A branch of an `IfElse` node — one or more condition groups combined with `group_logic`. |
|       `group_logic` | string | no | How the condition groups combine. Defaults to `and`. One of: `"and"`, `"or"`. |
|       `condition_groups` | array of object | no |  |
|         `logic` | string | no | How the conditions inside this group combine. Defaults to `and`. One of: `"and"`, `"or"`. |
|         `conditions` | array of CascadeCondition | yes |  |
|           `source_node_id` | string | yes | The `id` of the product node whose output is compared. |
|           `field` | string | yes | Exact output field path from that product's schema, e.g. `creditScore.fico9`. |
|           `operator` | string | yes |  One of: `"equals"`, `"not_equals"`, `"greater_than"`, `"greater_than_or_equal"`, `"less_than"`, `"less_than_or_equal"`, `"contains"`, `"not_contains"`, `"starts_with"`, `"ends_with"`, `"is_empty"`, `"is_not_empty"`, `"is_true"`, `"is_false"`. |
|           `value` | one of | no | The comparison value. Required for every operator except the unary ones (`is_empty`, `is_not_empty`, `is_true`, `is_false`), which accept `null` or no `value` at all. |
|             `option 1` | string, nullable | no |  |
|             `option 2` | number | no |  |
|             `option 3` | boolean | no |  |
|     `human_review` | CascadeBranch | no | A branch of an `IfElse` node — one or more condition groups combined with `group_logic`. |
|       `group_logic` | string | no | How the condition groups combine. Defaults to `and`. One of: `"and"`, `"or"`. |
|       `condition_groups` | array of object | no |  |
|         `logic` | string | no | How the conditions inside this group combine. Defaults to `and`. One of: `"and"`, `"or"`. |
|         `conditions` | array of CascadeCondition | yes |  |
|           `source_node_id` | string | yes | The `id` of the product node whose output is compared. |
|           `field` | string | yes | Exact output field path from that product's schema, e.g. `creditScore.fico9`. |
|           `operator` | string | yes |  One of: `"equals"`, `"not_equals"`, `"greater_than"`, `"greater_than_or_equal"`, `"less_than"`, `"less_than_or_equal"`, `"contains"`, `"not_contains"`, `"starts_with"`, `"ends_with"`, `"is_empty"`, `"is_not_empty"`, `"is_true"`, `"is_false"`. |
|           `value` | one of | no | The comparison value. Required for every operator except the unary ones (`is_empty`, `is_not_empty`, `is_true`, `is_false`), which accept `null` or no `value` at all. |
|             `option 1` | string, nullable | no |  |
|             `option 2` | number | no |  |
|             `option 3` | boolean | no |  |
|   `pass_steps` | array of string | no | `IfElse` only. Node ids to run when the `pass` branch matches. |
|   `human_review_steps` | array of string | no | `IfElse` only. Node ids to run when the `human_review` branch matches; the execution pauses with `needs_human_review: true` until a review decision resumes it. |
|   `fail_steps` | array of string | no | `IfElse` only. Node ids to run when no branch matches. |
|   `action_type` | string | no | `Action` only. One of: `"Approve"`, `"SendEmail"`, `"AdverseAction"`, `"InternalNotification"`. |
|   `email` | object | no | `Action` with `action_type: SendEmail`. Fields support `{{variable}}` interpolation from the execution context. |
|     `to` | string | no |  |
|     `subject` | string | no |  |
|     `body` | string | no |  |
|   `adverse_action` | object | no | `Action` with `action_type: AdverseAction`. `send_strategy: draft_first` parks the notice for human review before sending. |
|     `recipient` | string | no |  |
|     `action_taken` | string | no | The action box ticked on the notice: `denied` (application denied), `revoked` (credit revoked or terms changed unfavorably), `adverse_employment` (adverse employment action) or `other_action`. Cascades the AI designer generates always use `denied`. One of: `"denied"`, `"revoked"`, `"adverse_employment"`, `"other_action"`. |
|     `send_strategy` | string | no |  One of: `"draft_first"`, `"auto_send"`. |
|     `reason` | string | no |  |
|   `internal_notification` | object | no | `Action` with `action_type: InternalNotification`. Operator-facing notification settings. |
|   `wait` | object | no | `Wait` only. The delay before the next node runs. |
|     `duration` | number | no |  |
|     `unit` | string | no |  One of: `"seconds"`, `"minutes"`, `"hours"`, `"days"`, `"weeks"`. |
|   `target_step` | string | no | `GoTo` only. The node id to jump to. |

```json
[
  {
    "id": "step_applicant",
    "type": "ApplicantSource",
    "name": "Applicant",
    "next_step": [
      "step_credit"
    ]
  },
  {
    "id": "step_credit",
    "type": "BillingProduct",
    "name": "Credit report",
    "billing_product_code": "EQF1003",
    "next_step": [
      "step_score_check"
    ]
  },
  {
    "id": "step_score_check",
    "type": "IfElse",
    "name": "Score at least 650?",
    "branches": {
      "pass": {
        "group_logic": "and",
        "condition_groups": [
          {
            "logic": "and",
            "conditions": [
              {
                "source_node_id": "step_credit",
                "field": "creditScore.fico9",
                "operator": "greater_than_or_equal",
                "value": 650
              }
            ]
          }
        ]
      }
    },
    "pass_steps": [
      "step_approve"
    ],
    "fail_steps": [
      "step_adverse_action"
    ]
  },
  {
    "id": "step_approve",
    "type": "Action",
    "name": "Approve",
    "action_type": "Approve"
  },
  {
    "id": "step_adverse_action",
    "type": "Action",
    "name": "Adverse action",
    "action_type": "AdverseAction",
    "adverse_action": {
      "recipient": "{{applicant.email}}",
      "action_taken": "denied",
      "send_strategy": "draft_first",
      "reason": "Credit score below the minimum required for this property."
    }
  }
]
```

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.