TM Scenario Definition

Current schema for transaction monitoring scenario definitions, with per-customer-type and per-risk-tier thresholds

Field	Value
Schema ID	https://github.com/ksuk/merlon/schemas/tm_scenario_v2.json
JSON Schema dialect	https://json-schema.org/draft/2020-12/schema
Type	object
Required top-level fields	schema_version, scenario_id, name, type, conditions, severity

Properties

Name	Type	Required	Description
schema_version	string	Yes
scenario_id	string	Yes
detector	enum	No	Explicit evaluator binding required by schema v2.1; v2.0 files use a deprecated legacy ID binding.
name	string	Yes
description	string	No
type	enum	Yes
conditions	object	Yes
parameters	object	No
risk_tier_adjustments	object	No
evaluation_mode	enum	No
severity	enum	Yes
tags	array of string	No

scenario_id

Constraint	Value
Pattern	^[a-z][a-z0-9_]*$

detector

Constraint	Value
Enum	"structuring", "rapid_movement", "high_frequency_small_amount", "dormant_account_reactivation", "high_risk_country_transfer"

type

Constraint	Value
Enum	"aggregation"

conditions

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
transaction_type	array of string	No
aggregation	object	No
threshold	object	No
absolute_threshold	number	No
additional	object	No

conditions.aggregation

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
field	string	No
function	string	No
period	string	No
group_by	string	No

conditions.threshold

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
by_customer_type	object	No

conditions.threshold.by_customer_type

Name	Type	Required	Description
(any key)	object	—

conditions.threshold.by_customer_type.*

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
by_risk_tier	object	No

conditions.threshold.by_customer_type.*.by_risk_tier

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
LOW	number	No
MEDIUM	number	No
HIGH	number	No

conditions.additional

Constraint	Value
Additional properties	forbidden

Name	Type	Required	Description
min_transactions	number	No
min_transaction_count	number	No
individual_below	number	No
inbound_threshold	number	No
outbound_threshold	number	No
outbound_ratio_min	number	No
window_hours	number	No
count_threshold	number	No
max_amount_per_txn	number	No
dormant_days	number	No
reactivation_threshold	number	No
threshold_amount	number	No
high_risk_countries	array of string	No

evaluation_mode

Constraint	Value
Enum	"realtime", "batch", "both"
Default	"batch"

severity

Constraint	Value
Enum	"LOW", "MEDIUM", "HIGH", "CRITICAL"

Full schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/ksuk/merlon/schemas/tm_scenario_v2.json",
  "title": "TM Scenario Definition v2",
  "type": "object",
  "required": [
    "schema_version",
    "scenario_id",
    "name",
    "type",
    "conditions",
    "severity"
  ],
  "additionalProperties": false,
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "scenario_id": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]*$"
    },
    "detector": {
      "type": "string",
      "enum": [
        "structuring",
        "rapid_movement",
        "high_frequency_small_amount",
        "dormant_account_reactivation",
        "high_risk_country_transfer"
      ],
      "description": "Explicit evaluator binding required by schema v2.1; v2.0 files use a deprecated legacy ID binding."
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "aggregation"
      ]
    },
    "conditions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "transaction_type": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "aggregation": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "field": {
              "type": "string"
            },
            "function": {
              "type": "string"
            },
            "period": {
              "type": "string"
            },
            "group_by": {
              "type": "string"
            }
          }
        },
        "threshold": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "by_customer_type": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "by_risk_tier": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "LOW": {
                        "type": "number"
                      },
                      "MEDIUM": {
                        "type": "number"
                      },
                      "HIGH": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "absolute_threshold": {
          "type": "number"
        },
        "additional": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "min_transactions": {
              "type": "number"
            },
            "min_transaction_count": {
              "type": "number"
            },
            "individual_below": {
              "type": "number"
            },
            "inbound_threshold": {
              "type": "number"
            },
            "outbound_threshold": {
              "type": "number"
            },
            "outbound_ratio_min": {
              "type": "number"
            },
            "window_hours": {
              "type": "number"
            },
            "count_threshold": {
              "type": "number"
            },
            "max_amount_per_txn": {
              "type": "number"
            },
            "dormant_days": {
              "type": "number"
            },
            "reactivation_threshold": {
              "type": "number"
            },
            "threshold_amount": {
              "type": "number"
            },
            "high_risk_countries": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "type": "object"
    },
    "risk_tier_adjustments": {
      "type": "object"
    },
    "evaluation_mode": {
      "type": "string",
      "enum": [
        "realtime",
        "batch",
        "both"
      ],
      "default": "batch"
    },
    "severity": {
      "type": "string",
      "enum": [
        "LOW",
        "MEDIUM",
        "HIGH",
        "CRITICAL"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}