Anatomy of a Rule

​

1.1 The Complete Structure

rule HighValueTransactionCheck {
    description "Flags any single transaction exceeding $10,000 for manual review."

    when amount > 10000

    then review
         score  0.7
         reason "Transaction amount exceeds $10,000 high-value threshold"
}

​

1.2 The rule Block

rule <RuleName> { ... }

• The rule keyword is optional but strongly recommended for readability. The parser will accept an identifier followed by { as a valid rule start.
• <RuleName> is an identifier, not a string. It must start with a letter or underscore, and can contain letters, digits, and underscores.
• There is one rule per .ws file. The parser reads a single rule from the input.
• The entire body of the rule is enclosed in curly braces { }.

• Use PascalCase or PascalCase_With_Underscores.
• The name should describe the fraud pattern or policy it enforces.
• Good: HighValueTransactionCheck, SanctionedCountryCheck, BlockIfPreviousFailed
• Bad: rule1, test, myRule

​

1.3 The description Clause

description "<text>"

• The value must be a double-quoted string.
• It is optional in the parser, but mandatory in practice. A rule without a description is a rule that will be misunderstood.
• Write for a non-technical audience: compliance officers, auditors, and future teammates.

// Good: Explains the what, and implies the why.
description "Blocks transactions to countries on the OFAC sanctions list."

// Good: Specific about the threshold and the regulatory driver.
description "Flags any single transaction over $10,000 for AML reporting (BSA/CTR requirement)."

// Bad: Too vague to be useful.
description "Checks amount."

​

1.4 The when Clause

when <condition>
 and <condition>
 or  <condition>

• Contains one or more conditional expressions.
• Multiple conditions are joined by and or or logical operators.
• If the entire when clause evaluates to true, the then clause executes.
• If it evaluates to false, the rule silently passes — no verdict is produced.
• A rule MUST have a when clause. The parser will reject a rule without one.

​

1.5 The then Clause

then <verdict>
     score  <number>
     reason "<text>"

• A rule MUST have a then clause. The parser will reject a rule without one.
• score and reason are optional. If omitted, score defaults to 0.0 and reason defaults to "No reason provided".
• score and reason can appear in any order after the verdict.

​

1.6 Fully Annotated “Hello World” Example

rule DormantAccountActivity {
    // ─── DESCRIPTION ───────────────────────────────────────────────────────
    // Provides context for analysts and auditors.
    description "Unusual activity after long period of account dormancy."

    // ─── WHEN ──────────────────────────────────────────────────────────────
    // Two conditions joined by 'and'. BOTH must be true.
    // Condition 1: Access nested metadata via dot notation.
    // Condition 2: A simple numeric comparison on a top-level field.
    when metadata.days_since_last_transaction > 90
     and amount > 1000

    // ─── THEN ──────────────────────────────────────────────────────────────
    // Verdict: 'review' (send to a human analyst queue).
    // Score: 0.7 (high confidence this is suspicious).
    // Reason: A clear explanation for the analyst.
    then review
         score   0.7
         reason  "High-value transaction after extended account inactivity"
}