Skip to content
RUMLRUML

Open Format for Digital Law

3.6 Operators

3.6 Operators

The operator of a node determines how the results of ALL its direct children are aggregated.

OperatorDescriptionDetails
AND / NOT_ANDConjunction and negated conjunction3.6.1
OR / NOT_ORDisjunction and negated disjunction3.6.2
XOR / NOT_XORDisjunction and negated disjunction with short-circuit3.6.3
DELEGATEDCombination defined by a capability carried in the node3.6.4
undefinedNot yet defined (draft status)3.6.5

Evaluation mode

A rulemap is evaluated in one of two modes:

  • optimized: apply short-circuit rules depending on the operator
  • complete: evaluate every child node without short-circuit

Leaf nodes

A leaf node has nothing to combine. Outside a draft, it MUST NOT have an operator; in a draft (metadata.status: "draft"), it MAY have any of the operators, including DELEGATED and undefined, and an evaluator ignores it (Rule NODE-07NODE-07 A parser MUST accept the optional node fields of 3.5.3, present or absent, except operator on a leaf node: a leaf node MUST NOT have operator unless metadata.status is draft; in a draft, a parser MUST accept any of the eight operators of 3.6 on a leaf node.). The result of a leaf node is determined by its capabilities (see chapter 4)

3.6.1 AND and NOT_AND

In optimized mode, the evaluator MUST check the child node results one after another.

  • If a child node yields false, it MUST yield false immediately. Child nodes that have not been inspected MUST be set to ignored in the RUML-result.
  • If a child node yields undefined, it MUST yield undefined immediately. Child nodes that have not been inspected MUST be set to ignored in the RUML-result.
  • If all child nodes yield true, it MUST yield true.

In complete mode, the evaluator MUST check all child results together in the following order

  • If any child resulted in false, it MUST yield false
  • If any child resulted in undefined, it MUST yield undefined
  • If all child nodes resulted in true, it MUST yield true

NOT_AND MUST apply the same logic but yield true when AND would yield false and vice versa

3.6.2 OR and NOT_OR

In optimized and complete mode, the evaluator MUST check all child results together in the following order

  • If any child resulted in true, it MUST yield true.
  • If any child resulted in undefined, it MUST yield undefined.
  • If all child nodes resulted in false, it MUST yield false.

NOT_OR MUST apply the same logic but yield true when OR would yield false and vice versa

3.6.3 XOR and NOT_XOR

XOR does not refer to the logical exclusive XOR (where two true inputs yield false), but to the legal XOR meaning that child nodes are deliberately constructed such that only one can be true. The evaluator behaves like a disjunction (OR) with early exit on the first true.

In optimized mode, the evaluator MUST check the child node results one after another.

  • If a child node yields true, it MUST yield true immediately. Child nodes that have not been inspected MUST be set to ignored in the RUML-result.
  • If a child node yields undefined, it MUST yield undefined immediately. Child nodes that have not been inspected MUST be set to ignored in the RUML-result.
  • If all child nodes yield false, it MUST yield false.

In complete mode, the evaluator MUST check all child results together in the following order

  • If any child resulted in true, it MUST yield true.
  • If any child resulted in undefined, it MUST yield undefined.
  • If all child nodes resulted in false, it MUST yield false.

NOT_XOR MUST apply the same logic but yield true when XOR would yield false and vice versa

3.6.4 The DELEGATED Operator

The DELEGATED operator uses a capability to compute the result from the child node results.

It can be used for combinations the logical operators cannot express, in particular threshold rules (“at least three of the following criteria”), tolerance rules (“at most one requirement may be missing”), majority and quorum rules, and rules that negate a single child rather than the whole node.

Binding to a combiner

The rule itself is carried by a combiner — a capability on the node that determines the node’s status from the results of its children. The official combiner is ruml:expression (see Chapter 4.14); a non-official can be used as well (see Custom combiners below).

A parent node has a combiner if and only if its operator is DELEGATED:

  • Outside a draft, a node with operator: "DELEGATED" MUST have a non-empty children array; a node with operator: "DELEGATED" and children MUST carry exactly one capability entry whose capability has the combiner role (rule OP-02) (Rule OP-02OP-02 Outside a draft, a node with operator: "DELEGATED" MUST have children. A node with operator: "DELEGATED" and children MUST have exactly one entry of a capability with the combiner role; for a ruml:draft/ or reverse-domain capability, the role is the one declared at the root. In a draft, a parser MUST accept that operator on a leaf node without a combiner (NODE-07).). In a draft, a leaf node MAY have operator: "DELEGATED" without a combiner; the operator is ignored like any operator on a leaf (Rule NODE-07NODE-07 A parser MUST accept the optional node fields of 3.5.3, present or absent, except operator on a leaf node: a leaf node MUST NOT have operator unless metadata.status is draft; in a draft, a parser MUST accept any of the eight operators of 3.6 on a leaf node.).
  • A node carrying a combiner entry MUST use operator: "DELEGATED" (rule CAP-08) (Rule CAP-08CAP-08 An entry of a capability with the combiner role MUST NOT appear on a node whose operator is not DELEGATED.). A combiner therefore never sits on a leaf, nor on a node with a logical operator.

Neither half is valid alone. A tool that does not know the combiner therefore cannot mistake such a node for a logical one: the operator is unknown to it and the file is rejected.

Exception to the leaf restriction

A combiner carries the combiner role, not decision, and is the only kind of capability that decides a node with children. The restriction in Chapter 4.1 — decision capabilities are leaf-only — applies to ruml:query and ruml:ai-query, which decide a node instead of its children. A combiner decides a node from its children and therefore requires them.

The combiner contract

The operator delegates the combination rule, not the guarantees that make a rulemap auditable. Every combiner, official or not, MUST:

  1. Yield true, false or no result — never a number, a string or a structure. Any other result MUST yield status undefined.
  2. Carry a human-readable description in its node-level payload, stating the rule in prose. The operator DELEGATED does not say what the node does, so without this the rulemap cannot be reviewed without reading code (rule OP-04) (Rule OP-04OP-04 The node-level payload of a combiner MUST have a non-empty prose description.).
  3. Yield undefined without running as soon as any child is undefined; JSONata is two-valued and would otherwise count such a child as not fulfilled, so a threshold rule would look determined when it is not.
  4. Consume all children: the operator MUST NOT short-circuit (rule OP-03) (Rule OP-03OP-03 An evaluator MUST NOT short-circuit a node with operator: "DELEGATED"; it evaluates every child before the combiner runs.).

A combiner SHOULD be deterministic and reproducible from the same inputs. It MAY use non-deterministic input, such as a random number or the current time (Rule OP-05OP-05 A parser MUST accept a combiner that uses non-deterministic input, including a ruml:expression that calls $random, $now, $millis or $eval.); it then SHOULD record the values it drew in the node result.

A combiner SHOULD record in the node result what it saw — at least the child statuses it consumed, any datapoint values it read, and the value it computed — so the decision can be reconstructed from the RUML-Result file alone.

The role of a capability says where it may sit; this contract says what it must deliver to sit there. Together they are what a combiner is; RUML defines no separate capability type.

Custom combiners

Any capability with the combiner role MAY act as a combiner, including a third-party one under the reverse-domain convention (see Chapter 4.4) (Rule OP-06OP-06 A parser MUST accept any capability declared at the root with the combiner role, including a reverse-domain one, as the combiner of a DELEGATED node.):

"capabilities": [
{
"id": "com.example/expression",
"required": true,
"role": "combiner"
}
]

Whether a custom capability is a combiner is defined by the parser and evaluator that implement it. Its root-level entry MUST declare the combiner role (rules CAP-03, OP-02); a parser that implements the capability checks the declared role against its implementation (rule CAP-04) (Rule CAP-03CAP-03 The root entry of a ruml:draft/ or reverse-domain capability MUST declare role., Rule OP-02OP-02 Outside a draft, a node with operator: "DELEGATED" MUST have children. A node with operator: "DELEGATED" and children MUST have exactly one entry of a capability with the combiner role; for a ruml:draft/ or reverse-domain capability, the role is the one declared at the root. In a draft, a parser MUST accept that operator on a leaf node without a combiner (NODE-07)., Rule CAP-04CAP-04 A parser that implements a ruml:draft/ or reverse-domain capability MUST reject the file if the declared role differs from the role it implements.). See Chapter 4.1 for the roles and the difference between combiner and decision.

required: true is what makes rule CAP-01 reject the file in a tool that does not implement the combiner, rather than leaving a node with an operator and no rule behind it.

A custom combiner makes the rulemap non-portable

An unknown leaf decision capability leaves one leaf undefined while the rest of the rulemap still evaluates. An unknown combiner, declared required: true as it must be, causes the whole document to be rejected. A rulemap using a non-ruml: combiner is therefore readable only by tools that implement it. The official combiner set grows by revision of this specification; a proprietary combiner is a deliberate trade of portability for expressiveness.

What the expression sees

The expression is evaluated against the same input document as a ruml:query expression, so datapoints are addressed by their id (dp_alter). In addition, the results of the node’s direct children are bound to the variable $children:

FieldTypeDescription
lexIdStringThe child’s lexId
labelStringThe child’s label
statusStringThe child’s status: "true" or "false" — the expression does not run when a child is undefined

The array is in children order. Only direct children are visible; a deeper result is reached by the intermediate node aggregating its own children in turn.

Evaluation rules

  • The operator MUST NOT short-circuit. All children MUST be evaluated before the expression runs, and a node with operator: "DELEGATED" MUST NOT cause a child to receive status ignored with reason.type: "shortCircuit" (Rule OP-03OP-03 An evaluator MUST NOT short-circuit a node with operator: "DELEGATED"; it evaluates every child before the combiner runs.). A count over partially evaluated children would be wrong rather than merely incomplete.
  • The expression MUST evaluate to a boolean. Any other result — including no result — MUST yield status undefined, with a reason of type default whose message SHOULD name the offending value.
  • Expressions SHOULD be deterministic. The non-deterministic JSONata functions $random, $now and $millis, and $eval, MAY be used; an expression using them is no longer guaranteed to be reproducible from the same inputs (Rule OP-05OP-05 A parser MUST accept a combiner that uses non-deterministic input, including a ruml:expression that calls $random, $now, $millis or $eval.). $eval runs a string as an expression, so the rule actually applied need not be visible in expression itself — description then carries all the more weight.
  • An expression whose result is equivalent to a logical operator (for example $children[0].status = "true" and $children[1].status = "true") SHOULD be reported as a warning; the logical operator is the reviewable form.

Examples

At least three of the listed criteria:

"1": {
"id": "0eb360a6-626a-406d-89a1-9f434ced141b",
"operator": "DELEGATED",
"label": "Mindestens drei Merkmale erfüllt",
"children": ["3", "4", "5", "6", "7"],
"capabilities": [
{
"id": "ruml:expression",
"payload": {
"description": "Mindestens drei der fünf Merkmale müssen erfüllt sein",
"expression": "$count($children[status = 'true']) >= 3"
}
}
]
}

At most one requirement may be missing:

"expression": "$count($children[status = 'false']) <= 1"

Majority of the children that were evaluated:

"expression": "$count($children[status = 'true']) * 2 > $count($children)"

Subsidiarity — the second child only applies if the first does not:

"expression": "$children[0].status = 'false' and $children[1].status = 'true'"

A fiction that overrides the children entirely:

"expression": "dp_alter >= 65 or $count($children[status = 'true']) = 3"

Recording the result

The node’s result carries the expression, the child statuses it saw and the computed value, so the decision can be reconstructed from the RUML-Result file alone — see Chapter 4.14.

3.6.5 The undefined operator

undefined means the operator is not yet defined. It MAY be used during creation in files with status draft, MUST NOT be used in files with any other status, and MUST be replaced by a valid operator before finalization (status review, approved, inForce) (Rule OP-07OP-07 operator: "undefined" MUST NOT occur unless metadata.status is draft; in a draft, a parser MUST accept it.). It is the default value when creating a new node. On a leaf node (without children), the operator is ignored; outside a draft, a leaf node MUST NOT have an operator at all, so undefined on a leaf is removed rather than replaced (Rule NODE-07NODE-07 A parser MUST accept the optional node fields of 3.5.3, present or absent, except operator on a leaf node: a leaf node MUST NOT have operator unless metadata.status is draft; in a draft, a parser MUST accept any of the eight operators of 3.6 on a leaf node.).

StatusRule
draftundefined MAY occur (Rule OP-07OP-07 operator: "undefined" MUST NOT occur unless metadata.status is draft; in a draft, a parser MUST accept it.)
review, approved, inForce, suspended, expired, replacedundefined MUST NOT occur → validation error (Rule OP-07OP-07 operator: "undefined" MUST NOT occur unless metadata.status is draft; in a draft, a parser MUST accept it.)

Tools SHOULD display a warning for undefined operators. Tools MAY offer automatic replacement with a default operator (e.g., AND).

Conformance tests