3.6 Operators
3.6 Operators
The operator of a node determines how the results of ALL its direct children are aggregated.
| Operator | Description | Details |
|---|---|---|
AND / NOT_AND | Conjunction and negated conjunction | 3.6.1 |
OR / NOT_OR | Disjunction and negated disjunction | 3.6.2 |
XOR / NOT_XOR | Disjunction and negated disjunction with short-circuit | 3.6.3 |
DELEGATED | Combination defined by a capability carried in the node | 3.6.4 |
undefined | Not 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 operatorcomplete: 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 yieldfalseimmediately. Child nodes that have not been inspected MUST be set toignoredin the RUML-result. - If a child node yields
undefined, it MUST yieldundefinedimmediately. Child nodes that have not been inspected MUST be set toignoredin the RUML-result. - If all child nodes yield
true, it MUST yieldtrue.
In complete mode, the evaluator MUST check all child results together in the following order
- If any child resulted in
false, it MUST yieldfalse - If any child resulted in
undefined, it MUST yieldundefined - If all child nodes resulted in
true, it MUST yieldtrue
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 yieldtrue. - If any child resulted in
undefined, it MUST yieldundefined. - If all child nodes resulted in
false, it MUST yieldfalse.
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 yieldtrueimmediately. Child nodes that have not been inspected MUST be set toignoredin the RUML-result. - If a child node yields
undefined, it MUST yieldundefinedimmediately. Child nodes that have not been inspected MUST be set toignoredin the RUML-result. - If all child nodes yield
false, it MUST yieldfalse.
In complete mode, the evaluator MUST check all child results together in the following order
- If any child resulted in
true, it MUST yieldtrue. - If any child resulted in
undefined, it MUST yieldundefined. - If all child nodes resulted in
false, it MUST yieldfalse.
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-emptychildrenarray; a node withoperator: "DELEGATED"andchildrenMUST carry exactly one capability entry whose capability has thecombinerrole (ruleOP-02) (Rule OP-02OP-02 Outside a draft, a node withoperator: "DELEGATED"MUST havechildren. A node withoperator: "DELEGATED"andchildrenMUST have exactly one entry of a capability with thecombinerrole; for aruml: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 haveoperator: "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, exceptoperatoron a leaf node: a leaf node MUST NOT haveoperatorunlessmetadata.statusisdraft; 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"(ruleCAP-08) (Rule CAP-08CAP-08 An entry of a capability with thecombinerrole MUST NOT appear on a node whoseoperatoris notDELEGATED.). 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:
- Yield
true,falseor no result — never a number, a string or a structure. Any other result MUST yield statusundefined. - Carry a human-readable
descriptionin its node-level payload, stating the rule in prose. The operatorDELEGATEDdoes not say what the node does, so without this the rulemap cannot be reviewed without reading code (ruleOP-04) (Rule OP-04OP-04 The node-level payload of a combiner MUST have a non-empty prosedescription.). - Yield
undefinedwithout running as soon as any child isundefined; 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. - Consume all children: the operator MUST NOT short-circuit (rule
OP-03) (Rule OP-03OP-03 An evaluator MUST NOT short-circuit a node withoperator: "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:
| Field | Type | Description |
|---|---|---|
lexId | String | The child’s lexId |
label | String | The child’s label |
status | String | The 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 statusignoredwithreason.type: "shortCircuit"(Rule OP-03OP-03 An evaluator MUST NOT short-circuit a node withoperator: "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 typedefaultwhosemessageSHOULD name the offending value. - Expressions SHOULD be deterministic. The non-deterministic JSONata functions
$random,$nowand$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 aruml:expressionthat calls$random,$now,$millisor$eval.).$evalruns a string as an expression, so the rule actually applied need not be visible inexpressionitself —descriptionthen 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.).
| Status | Rule |
|---|---|
draft | undefined 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, replaced | undefined 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).