Rule language reference

Everything you may write inside a when or a then statement comes from one small expression grammar. This page is that grammar in full: what parses, what it evaluates to, and what the language has no syntax for at all.

The rule header, the execution cycle and rule-set loading are on Writing rules, the callable surface, in, out, audit and the helper namespaces, is on Built-in functions.

The whole grammar

rule Name ["description"] [salience N] { when expression then statement; ... }

statement   = target = expression      // also +=  -=  *=  /=
            | expression               // in practice, a method call

expression  = expression * / %      expression
            | expression + - & |    expression
            | expression == != > < >= <=  expression
            | expression &&         expression
            | expression ||         expression
            | [!] ( expression )
            | atom

atom        = literal
            | name
            | atom . name             // member access
            | atom [ expression ]     // index
            | name ( args )           // function call
            | atom . name ( args )    // method call
            | ! atom

That is the complete list of forms. There is no other statement kind, no other operator and no other way to construct a value.

Where expressions appear

Position	Constraint
when	Must evaluate to a boolean. when 1 fails with the when is not a boolean expression : 1
Right side of an assignment	Any expression
A call argument	Any expression, including a nested call
Inside [ ]	Any expression: rows[1 - 1] works. One level of indexing only
salience	Not an expression. Integer literal only

Operators and precedence

Tightest first. All binary operators are left-associative.

Level	Operators	Notes
1	. [ ] ( )	Member access, index, call. Postfix, applied left to right
2	!	Applies to a single atom or a parenthesised expression
3	* / %
4	+ - & |	Bitwise & and | sit here, tighter than comparison
5	== != > < >= <=
6	&&	Short-circuits
7	||	Short-circuits

1 + 2 * 3 == 7 is true. false && false || true is true. 6 & 3 == 2 is true, the & binds first, unlike C where the comparison would win. Parenthesise bitwise operands if you use them at all.

! binds to one atom, not to a comparison: !true == false parses as (!true) == false. To negate a comparison, parenthesise it, !(1 > 2).

There is no ternary, no in operator, no between, no + that produces anything but a number or a string, and no unary minus outside a numeric literal, the - in -5 belongs to the literal, so -x where x is a variable fails the load; write 0 - x.

Short-circuiting is load-bearing

&& and || short-circuit, and that is the only way to make a conditional access safe:

when
    out.Has("tier") && out.Get("tier") == "gold"

The guard is required, not defensive. Without it the right-hand comparison runs against a value that is not there and aborts the whole execution, see Comparison below.

A guard that reads out is only half the job: the rule that wrote the value must also call Changed("out"), or a later rule’s when keeps the reading it memoised on the first cycle and never fires. Rule patterns has the full idiom.

Literals

Form	Example	Evaluates to
Double-quoted string	"invoice"	string
Single-quoted string	'invoice'	string
Decimal integer	42, -5	int64
Hexadecimal integer	0x1F (31), -0x10 (−16)	int64
Octal integer	010 (8)	int64
Decimal float	1.5, .5, 1.5e2, -1.5	float64
Hexadecimal float	0x1p-2 (0.25)	float64
Boolean	true, false	bool
Nil	nil	untyped nil

Strings take backslash escapes: "say \"hi\"" and "a\nb" both work, the doubled-quote form "a""b" lexes as one token but fails the load when it is unquoted.

true, false and nil are matched case-insensitively, like the keywords.

Caution

The int64/float64 split has no coercion at a call boundary. math.Min(10, 20) panics with reflect: Call using int64 as type float64. Write math.Min(10.0, 20.0). The mirror case is just as fatal: a parameter typed int64 rejects 5.0, a function whose parameter is a narrower integer, float32 or a named integer type cannot be called at all, because no literal produces those types. Built-in functions marks every signature this rules out.

Arithmetic

Arithmetic follows the literal types, and the results surprise people coming from Go.

Expression	Result	Type
2 + 3	5	int64
3 * 4	12	int64
7 / 2	3.5	float64
1 / 3	0.3333333333333333	float64
1 / 0	+Inf	float64
1 + 2.5	3.5	float64
7 % 2	1	int64
9223372036854775807 + 1	-9223372036854775808	int64
"n=" + 5	"n=5"	string
"n=" + 2.5	"n=2.500000"	string

Four things follow from that table:

• Division always yields a float. 7 / 2 is 3.5, never 3. There is no integer division operator and no truncation. Anything you divide is float64 from that point on, including as a function argument.
• Division by zero does not fail. It produces +Inf and the rule carries on, so a zero denominator surfaces later as a nonsense output rather than an error.
• % is int64-only. 7 % 2.0 aborts the execution with can not use data type of float64 in modulo; "a" % 2 aborts with the string form of the same message.
• Integer overflow wraps silently at the int64 boundary.

Float equality is exact-bit equality: 0.1 + 0.2 == 0.3 is false. Compare with a tolerance instead, math.Abs(0.1 + 0.2 - 0.3) < 0.000001 is true.

+ concatenates when either side is a string, formatting a number operand as it goes, a float concatenates in fixed-point form, "n=" + 2.5 is "n=2.500000", not "n=2.5". Use strings.Sprintf rather than + when the exact text matters.

Comparison

Operands	Behaviour
Two numbers	Compared numerically across int64 and float64. 1 == 1.0 is true
Two strings	Lexicographic. "abc" < "abd" is true
Two booleans	== and != only
String on the left, number on the right, with == / !=	No error. "5" == 5 is simply false
Number on the left, string on the right, with == / !=	Aborts: can not use data type of string in EQ comparison
String vs number, with > < >= <=	Aborts either way: "5" > 5 gives can not compare data type of string to int64 in GT comparison, 5 > "5" gives can not use data type of string in GT comparison

Mixed-type equality is not symmetric: which side the string is on decides whether you get false or a dead execution. Never rely on == to compare across types, convert first.

Caution

Never compare anything to nil, and never compare a value you have not confirmed is present. Both raise reflect: call of reflect.Value.Type on zero Value, and because the engine aborts on any failed evaluation, that discards the entire run. Every value already collected is thrown away. x != nil fails even when x holds a value. IsNil() is not a substitute; it panics on anything that cannot be nil, including a string. Use in.Has(...) / out.Has(...) with &&.

Reading a key that is not in a map fact fails the same way, with this node identified as "<fact>" have no selector with specified key.

Logical joining

&&, || and ! take booleans and nothing else. There is no truthiness:

when 1 && true     // can not use data type of int64 in Logical AND comparison
when !1            // the when is not a boolean expression : !1

when accepts exactly one expression. Two conditions on consecutive lines is a load error, not an implicit AND, join them with &&.

Member access and indexing

Which accessor is legal depends on the shape the fact decoded to, not on how the value looks.

Fact type	Accessor	Example
Struct or pointer to struct	Dot, exported fields only. No surface supplies one	order.Total > 1000
Object fact. A -f fact file, or a nested object on the POST /rule body	Bracket	order["Total"] > 1000
Slice or array	Bracket, integer index	rows[0]
Result of a call	Bracket, chained directly	"a,b".Split(",")[1]
A value reached through one bracket already	Neither. Both accessors abort	doc["header"]["total"]

Both forms also work on the left of an assignment, and both mutate the caller’s fact in place:

then
    order.Approved = true;
    page["reviewed"] = "yes";

The index may be any expression, including a variable: k = "Total"; order[k].

Caution

Dot access on a map fact aborts the whole execution. A fact loaded from a -f file on the command line is decoded with encoding/json into map[string]any, so order.Total fails with:

evaluating expression in rule 'R' the when raised an error. got left hand expression error.
got this node identified as "order" is not referencing to an object

Write order["Total"]. Dot access applies to struct-typed facts, and neither surface produces one: kis rules decodes JSON into maps and rules.svc decodes the request body into an ordered map. Every fact you supply takes bracket access.

Note

A nested fact object reads the same on both surfaces. order["Total"] works whether the fact came from kis rules -f order=order.json or from a nested object on the POST /rule body, and order.Total aborts on both for the reason above. Write bracket access once and the rule set runs unchanged either way.

The reserved objects on the request body are not facts. bbox is document input. It is read before the fact map is built, nesting inside it is expected, and every document binding a rule calls behaves identically on both surfaces. Under the CLI the document arrives as kis rules -b page=invoice.bbox; over HTTP it is the bbox object on the same POST /rule body that carries the facts. audit is the trail request. See The rules service.

Caution

Two-level indexing into decoded JSON does not work, for objects or for arrays. Every value inside a decoded payload is interface-typed, and the engine will not index through an interface. Both of these abort the execution:

doc["header"]["total"]   // got doc[string->header] is not an array nor map
rows[0]["name"]          // got rows[0] is not an array nor map

Assigning the intermediate to a variable first does not rescue it, h = doc["header"]; h["total"] fails with h is not an array nor map. One level always works (doc["header"], rows[0], rows.Len()), so a nested payload looks fine until a rule reaches the second level.

The fix is on the input side: flatten the object into top-level keys, or send the inner object as a fact of its own. Decoding JSON never produces the concretely typed container that would index through, so no flag, file layout or request shape rescues a two-level read.

Note

Numbers decoded from JSON arrive as float64, whatever they looked like in the payload. Comparisons still work, amount > 100 is fine, but amount % 2 aborts with can not use data type of float64 in modulo, and passing the value to an int64 parameter fails.

Strings are not indexable. "abc"[0] panics with a nil pointer dereference.

.Len(), .ToUpper(), .In(...) and the rest are methods on a value, not grammar, see Methods on values.

Variables

name = expression; in a then block creates or overwrites a top-level name. +=, -=, *= and /= also parse; /= follows the division rule, so x = 7; x /= 2 leaves x at 3.5. Assignment is a then-only construct, when x = 1 fails the load. Write when x == 1.

Variables hold scalars, strings, numbers, booleans, and survive across rules within one execution.

Caution

A variable cannot hold a map or a slice in any useful way. Indexing one fails with <var> is not an array nor map, and passing one to a function fails with reflect: Call using zero Value argument. Chain the index or the call directly onto the expression that produced the collection, or stage it with in.MemSet.

Identifiers

A name starts with a letter (including a Unicode letter) and continues with letters, digits or _. Step_1_Do is valid; 1Step fails the load.

Names are case-sensitive everywhere, including the string you pass to Retract. A name written in a when that no fact binds aborts the entire execution with got non existent key <name>.

What the language does not have

Each of these fails at load with a parse error. None is a runtime limitation you can work around with a flag.

You might write	Write instead
if c { ... } else { ... }	Two rules. The second carries the negated condition at a lower salience
for i = 0; i < 3; ... { }	One rule that re-fires, driven by a counter fact; see Rule patterns
c ? a : b	Two rules
"a" in "a","b"	"a".In("a","b"). A method on a string value, not an operator
["a", "b"]	Nothing. Supply the array as a top-level fact. A key in a -f file, or a top-level key on the POST /rule body
{"a": 1}	in.NewMapWithValues("a", 1), usable only as a direct call argument
Finding{RuleID: "x"}	Nothing: but nothing needs it. findings takes strings; see below
-x on a variable	0 - x
when x = 1	when x == 1
salience 1.5	An integer literal. salience -5 is legal, salience 1.5 is not
A then statement without a trailing ;	Terminate every then statement with ;
An empty then	At least one statement

There is also no return, break or continue; no variable declaration or type annotation; no function, import or include; and no string interpolation. A .grl file contains rule declarations and comments, nothing else.

Branching is expressed as a second rule with the opposite condition at a lower salience, Rule patterns has the idiom.

Caution

A load failure tells you how many syntax errors there are and nothing else. The parser’s per-error detail, line, column, offending token, is written to a logger that neither rules.svc nor the CLI installs, so it is discarded. All you get back is got 1 error(s) in grl the script, with no indication of which rule or which line. Load one .grl file at a time while you are still getting a rule set to parse.

Note

The missing struct literal does not cost you findings. findings takes strings throughout, findings.Add(ruleID, severity, category, message, fields), or the graded verbs findings.Error/Warn/Info/Critical(ruleID, category, message), precisely so that the grammar’s lack of a struct literal never blocks a rule. Any example showing findings.Add(Finding{...}) is written against the old surface and does not compile. See Findings for the full surface.

Continue with

• Writing rules: the rule header, when/then, rule sets and the execution cycle
• Built-in functions: every callable binding and which signatures the type rules rule out
• Rule patterns: guards, chaining, fallbacks and staging collections
• Troubleshooting: the same errors, indexed by symptom