3.5 Node Object
3.5 Node Object (Core Architecture)
3.5.1 Node Types by Role
In the flat map architecture, all nodes are stored directly in the nodes object. Node types are
derived from their logical role in the hierarchy, defined by lexId and children references:
| Type | Logical Role | Description | Identification |
|---|---|---|---|
| root | Root | The topmost node of the rulemap | Has the key "1" in the nodes object (LexID 1) |
| parent | Branch | Node with its own children | Has a non-empty children array |
| leaf | Leaf | Terminal node without children | Has no children array |
The following rules apply to the node types:
- The root node MUST exist (
Rule FMT-08FMT-08rulemap.nodesMUST contain an entry with key"1", the root node.). - The root node MUST NOT appear in the
childrenarray of any node (Rule NODE-05NODE-05 The root node"1"MUST NOT appear in anychildrenarray.). - A
childrenarray MUST NOT be empty (Rule NODE-06NODE-06childrenMUST NOT be empty.).
Important: The type MUST NOT be explicitly stored, as it is derived from the structure
(Rule NODE-03NODE-03 A node MUST NOT have fields other than those of 3.5; in particular it MUST NOT store its LexID (lexId), its parent or its type.).
Runtime status: The evaluation status of a node (pending, true, false, undefined,
ignored) is computed at runtime and is NOT part of the node definition. Storage of evaluation
results occurs exclusively in a separate RUML Result file (.ruml-result) (see
Chapter 5).
3.5.2 Required Fields of a Node
| Field | Type | Description |
|---|---|---|
id | UUID | MUST be present (Rule NODE-01NODE-01 A node MUST have id and label.). MUST be unique within the file, also against metadata.id (Rule NODE-08NODE-08 The id of a node MUST NOT equal the id of another node or metadata.id.). MUST conform to the format from 3.2.2 (Rule FMT-10FMT-10 Every UUID MUST be a lowercase UUID version 4 (pattern in 2.5).). |
label | String | MUST contain a human-readable label (Rule NODE-01NODE-01 A node MUST have id and label.). MUST have at least 1 character (Rule NODE-09NODE-09 label MUST NOT be empty.). |
Note on LexID: The LexID of a node is derived from the key in the nodes object (see
3.2.1). A separate lexId field is NOT required and MUST NOT be
used (Rule NODE-03NODE-03 A node MUST NOT have fields other than those of 3.5; in particular it MUST NOT store its LexID (lexId), its parent or its type.).
3.5.2a The operator Field
The operator field (type Enum) determines how a node combines the results of its children.
- A parent node MUST have an
operator; it applies to ALL direct children (Rule NODE-12NODE-12 A node withchildrenMUST haveoperator.). - A leaf node has nothing to combine. It MUST NOT have an
operatorunlessmetadata.statusisdraft; in a draft, a leaf node MAY have any operator, and an evaluator ignores it (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.). - The value MUST be one of the operators defined in 3.6 (
Rule OP-01OP-01operatorMUST be one of the eight values of 3.6.).
3.5.3 Optional Fields of a Node
A node MAY have any of the following fields; a parser MUST accept each of them, present or absent
(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.).
| Field | Type | Description |
|---|---|---|
children | Array[String] | MAY contain an ordered list of child references. Each entry MUST be a LexID reference (string, see 2.5) (Rule FMT-11FMT-11 Every key of rulemap.nodes and every entry of children MUST be a LexID, a string matching ^[1-9][0-9]*$.). Each referenced LexID MUST exist in the nodes object (Rule NODE-10NODE-10 Every entry of children MUST be a key of rulemap.nodes.). The same LexID SHOULD NOT appear more than once in one children array. The order is significant. |
altText | String | MAY contain an alternative/full text. SHOULD be used for UI display (tooltips, screen readers). If not set, label SHOULD be used. |
description | String | MAY contain a detailed description. MUST NOT exceed 10,000 characters (Rule NODE-11NODE-11 description MUST NOT exceed 10,000 characters.). |
capabilities | Array | MAY contain capability-specific data for this node, as an ordered list of { id, payload } entries; each entry MUST have both fields (Rule CAP-17CAP-17 Every entry of a node's capabilities MUST have id and payload, and payload MUST be an object.). Every id MUST correspond to a capability declared in the file (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.). Via capabilities, ruml:query, ruml:actions, and ruml:ai-query are provided, among others. See Chapter 4.3. |
metadata | Object | MAY contain additional metadata. SHOULD be used for non-structural information. |
decisionMode | Enum | MAY define the combination mode for multiple decision-relevant capabilities. Only relevant for leaf nodes with more than one decision capability. Permitted values: fallback, agreement, majority. Default: fallback. See Chapter 4.3. |
modular | Boolean | Marks the node as a modular node (definition see 6.2). A modular node MUST have modular: true (Rule MOD-01MOD-01 A node whose LexID appears more than once in the children arrays of the rulemap (a self-reference counts) MUST have modular: true.); a node that is not modular SHOULD NOT have it. |
Important rules:
- Restrictions for decision-relevant capabilities (
ruml:query,ruml:ai-query) are defined in the respective capability specification (see Chapter 4.8) - The norm a node represents and the texts it refers to are provided via the
capabilitiesentry withid: "ruml:text-reference"(anchors inrefs, see Chapter 4.12) - The
idof every entry in a node’scapabilitiesarray MUST be declared in the root-levelcapabilitiesarray of the same file (referential integrity, rule CAP-15 in chapter 08) (Rule CAP-15CAP-15 Theidof every entry of a node'scapabilitiesMUST be declared in the rootcapabilities.). The complete specification is found in Chapter 4.3.
Capability-provided node extensions
The following concepts are not direct node fields, but are provided via capabilities:
| Capability | Node field | Description |
|---|---|---|
ruml:query | capabilities entry id: "ruml:query" | Data-based query expression for leaf nodes — see Chapter 4.8 |
ruml:actions | capabilities entry id: "ruml:actions" | Actions for onTrue, onFalse, onUndefined — see Chapter 4.10 |
ruml:ai-query | capabilities entry id: "ruml:ai-query" | LLM-based decision — see Chapter 4.9 |
ruml:text-reference | capabilities entry id: "ruml:text-reference" | References to normative texts (laws, regulations) — see Chapter 4.12 |
3.5.4 Node Positions (Paths)
Node positions (paths) are computed at runtime from the tree structure and are NOT part of the RUML
file. The hierarchical position of a node is derived entirely from the children arrays and the
lexId structure in the nodes object.
For modular nodes (see Chapter 6), the same node can be reached via
different paths in the tree. Paths are computed at runtime and used in the results object of the
RUML Result file (see Chapter 5) as keys for evaluation results.