Language Reference

Overview

RuleDSL is a purpose-built language for writing business decision rules. It compiles to bytecode that evaluates deterministically: same input, same bytecode, same decision — every time, on every platform.

A rule file contains one or more named rules. Each rule has a condition (when) and an action (then). Rules are evaluated in priority order. The first rule whose condition matches produces the decision.

Rule Structure

Every rule follows this pattern:

rule rule_name priority 100 {
  when <condition>;
  then <actions>;
}

Components

Evaluation Order

Rules are evaluated by priority (highest first). Among rules with equal priority, source order applies. The first match wins — no further rules are evaluated after a decision is reached.

Expressions & Operators

Comparison Operators

Logical Operators

Use parentheses to control evaluation order: (a or b) and c

Arithmetic Operators

Standard precedence: * and / bind tighter than + and -. Use parentheses when in doubt.

Operator Precedence (Highest to Lowest)

Decision Types

# Simple decisions
then allow;
then decline;
then review;

# Velocity limit (requires now_utc_ms in input)
then limit 200 USD per 1 D;

Data Types

Numeric Literals

Numbers support integer, decimal, and scientific notation:

when amount > 10000;        # integer
when rate > 0.05;           # decimal
when amount > 1e6;          # scientific notation (1,000,000)
when rate > 2.5e-3;         # decimal + exponent (0.0025)

Currency-Tagged Numbers

Append a 3-letter currency code to a numeric literal for currency-aware comparisons:

when amount >= 1e4 USD;     # 10,000 USD
when amount >= 8000 EUR;    # 8,000 EUR

Dotted Paths

Access nested fields with dot notation:

when customer.risk_level > 70 and merchant.category == "gambling";

Assignments & Computed Values

The then clause can set output fields alongside the decision. These appear in the result and can be used by downstream systems.

rule fraud_signal priority 100 {
  when amount > 3000 and ip_country in [NG, RU];
  then risk_score = 95,
       reason = "multi_signal_fraud",
       category = "high_risk",
       decline;
}

Assignments support arithmetic expressions:

then risk_score = (amount / 100) + velocity_1h, review;

Lists & Pattern Matching

IN Lists

Check if a value is a member of a list:

when ip_country in [TR, NG, RU, KP];
when channel in [ECOM, APP, WEB];

List items can be identifiers (bare words) or strings.

MATCH (Substring Matching)

Check if a text field contains a substring:

when email match "@example.com";
when card_bin match "41111";

Time & Velocity Limits

The limit decision enforces velocity caps over time windows:

then limit 500 USD per 1 D;    # max 500 USD per day
then limit 3 TRY per 1 H;      # max 3 transactions per hour

Time Units

Missing Values

If a referenced field is not provided in the input, it resolves to missing.

• missing is a distinct value — not null, not zero, not empty string.
• Comparisons involving missing produce a runtime diagnostic and the condition evaluates to false.
• The rule simply does not match. No crash. No undefined behavior.

This means you do not need defensive null checks. If a field might not exist, the rule safely skips:

# If customer.loyalty_tier is not in the input, this rule is skipped
rule vip_bypass {
  when customer.loyalty_tier == "platinum";
  then allow;
}

Determinism Guarantees

RuleDSL is deterministic by contract. These are not aspirational goals — they are enforced by the engine architecture:

The result: same bytecode + same input + same engine version = same decision. Always. On every platform.

Complete Examples

Transaction Risk Scoring

rule block_sanctioned priority 200 {
  when ip_country in [KP, IR, SY];
  then reason = "sanctioned", decline;
}

rule high_risk_geo priority 100 {
  when amount > 5000 and ip_country in [NG, RU];
  then risk_score = 90, reason = "geo_high", decline;
}

rule review_medium priority 50 {
  when amount > 1000 and amount <= 5000;
  then risk_score = 60, reason = "medium_amount", review;
}

rule allow_default {
  when true;
  then risk_score = 10, reason = "baseline", allow;
}

Spending Limits with Device Trust

rule block_new_device_high priority 100 {
  when is_new_device and amount > 2000;
  then reason = "new_device_risk", decline;
}

rule limit_daily priority 50 {
  when amount > 1000;
  then reason = "daily_cap", limit 500 USD per 1 D;
}

rule trusted_device priority 10 {
  when card_present and not is_new_device;
  then reason = "trusted", allow;
}

rule default_review {
  when true;
  then review;
}

Email & Channel Controls

rule flag_internal_email priority 100 {
  when email match "@internal\\.corp$";
  then reason = "internal_email", review;
}

rule block_risky_channel priority 50 {
  when channel in [ECOM, APP] and amount > 1000;
  then reason = "risky_channel", decline;
}

rule allow_other {
  when true;
  then allow;
}

Quick Reference

Keywords

Keywords are case-insensitive: WHEN, When, and when are equivalent.

Reserved Input Field

Further Reading

• Rule Cookbook — 12 copy-paste examples by business scenario
• Language Specification v1.0 — formal normative reference
• Error Reference — all 12 error codes with resolution steps
• Python Binding — quickstart for Python developers
• C# Binding — quickstart for .NET developers