4.3 Capability Data on Nodes
4.3 Capability Data on Nodes
Overview
Each node MAY carry its own capabilities field — independent of the identically named
capabilities array at root level (see Chapter 4.2). It contains the
extension data for the capabilities applicable to this node.
The field is part of the optional fields of the node object (see Chapter 3.5.3) and is subject to the same general rules: it does not need to be present; its absence has no effect on core processing.
Structure
"capabilities": [ { "id": "ruml:query", "payload": {/* ... */} }, { "id": "ruml:draft/ai-annotations", "payload": {/* ... */} }]id: A capability ID that is declared in the root-levelcapabilitiesarray.payload: An object whose inner structure is defined by the respective capability specification.
Both fields are required: every entry MUST contain id and payload (Rule CAP-17CAP-17 Every entry of a node's capabilities MUST have id and payload, and payload MUST be an object.). A capability
without node-level data, such as ruml:protocol, therefore MUST NOT appear in a node’s
capabilities array (Rule CAP-18CAP-18 ruml:protocol MUST NOT appear in a node's capabilities, neither inline nor in a RUML-EXT file.).
Referential Integrity
The id of each entry in a node’s capabilities array MUST be a capability ID that is declared in
the root-level capabilities array (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.).
Invalid Capability Reference
If a node’s capabilities array contains an entry whose id is not declared in the root-level
capabilities array, the parser MUST treat this as a validation error (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.). This rule
applies regardless of whether the parser knows the capability’s content or not.
Invalid — org.ruml.test/decision is not declared in the root capabilities array:
{ "$format": "RUML", "$specVersion": "1.0", "capabilities": [ { "id": "org.ruml.test/data", "role": "data" } ], "metadata": { "id": "fa906bd6-24f1-47f3-8ad5-ae3d5c745b56", "version": "1.0.0", "created": "2024-01-01T00:00:00Z", "modified": "2024-01-01T00:00:00Z", "status": "inForce", "validFrom": "2024-01-01T00:00:00Z" }, "rulemap": { "nodes": { "1": { "id": "ec36948d-fbb2-4815-985a-bd5e9375d934", "label": "Anspruch auf Schadensersatz", "capabilities": [ { "id": "org.ruml.test/decision", "payload": { "result": "true" } } ] } } }}Valid — capability correctly declared:
{ "$format": "RUML", "$specVersion": "1.0", "capabilities": [ { "id": "com.example/review-notes", "role": "data" } ], "metadata": { "id": "dc456c3b-cfa6-44a8-9617-cb5119bbe1ee", "version": "1.0.0", "created": "2024-01-01T00:00:00Z", "modified": "2024-01-01T00:00:00Z", "status": "inForce", "validFrom": "2024-01-01T00:00:00Z" }, "rulemap": { "nodes": { "1": { "id": "ec36948d-fbb2-4815-985a-bd5e9375d934", "label": "Anspruch auf Schadensersatz", "capabilities": [ { "id": "com.example/review-notes", "payload": { "status": "pending" } } ] } } }}Applicability to Node Types
The capabilities field MAY appear on any node type: root node, parent node, and leaf node
(Rule CAP-16CAP-16 A parser MUST accept capabilities on any node, and entries of capabilities with the data or reaction role on any node, in any order, also beside the combiner of a DELEGATED node.).
Restriction for decision-relevant capabilities: Capabilities with the decision role MUST NOT
be applied to anything other than leaf nodes (Rule CAP-07CAP-07 An entry of a capability with the decision role MUST NOT appear on a node with children.). The status of root and parent nodes is
determined exclusively by the tree structure and operators (see
Chapter 3.6). The role of each capability is defined in its
specification (see Chapter 4.1).
Capabilities with the data or reaction role MAY appear on any node type (Rule CAP-16CAP-16 A parser MUST accept capabilities on any node, and entries of capabilities with the data or reaction role on any node, in any order, also beside the combiner of a DELEGATED node.).
Likewise, it MAY appear on modular nodes (modular: true) and on nodes within modular subtrees. For
modular nodes, the capabilities data applies to all instantiations of the node (see
Chapter 3.5.3).
Repeated Capability IDs
Unlike the root-level array, whose ids are unique (see
Chapter 4.2), a node’s capabilities array MAY contain the
same id more than once if the capability’s role allows it (see Chapter 4.1):
| Role | Same id more than once on a node |
|---|---|
data | MUST NOT. One entry carries all of the node’s data for that capability. |
decision | MAY, e.g. two ruml:query entries with different expressions; decisionMode combines their results. |
combiner | MUST NOT. A node carries at most one combiner anyway (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).). |
reaction | MAY, e.g. two ruml:actions entries; they are processed in list order (see Field Order). |
The rule counts entries with the same id, not entries with the same role: a node MAY carry
ruml:text-reference and ruml:context side by side. The schema enforces it for the official
data capabilities; for ruml:draft/ and third-party ids the role comes from the root-level
declaration, so the check is a parser obligation (Rule CAP-06CAP-06 On one node, a capability with the data role MUST NOT have more than one entry; a parser MUST accept several entries of a capability with the decision or reaction role.).
Payload Type
The payload MUST be an object (Rule CAP-17CAP-17 Every entry of a node's capabilities MUST have id and payload, and payload MUST be an object.). Arrays, primitive values, and null MUST NOT be
used; a capability that carries a list places it in a named field of the object. The object’s inner
structure is defined by the capability specification.
"capabilities": [ { "id": "com.example/review-notes", "payload": { "status": "approved", "reviewer": "rechtsabteilung" } }, { "id": "ruml:draft/ai-annotations", "payload": { "annotations": [ { "type": "confidence", "value": 0.92 }, { "type": "source", "value": "gpt-4o" } ] } }]Complete Node Example
The following example shows a leaf node with two different capability extensions:
"2": { "id": "f32b5875-2557-499a-a9b5-bd5efdeab0fd", "label": "Volljährigkeit nachgewiesen", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_age >= 18" } }, { "id": "ruml:draft/ai-annotations", "payload": { "confidence": 0.97, "lastReviewed": "2024-09-15", "reviewer": "llm-assistant-v2" } } ]}Combination Mode (decisionMode)
If a leaf node contains multiple capabilities with the decision role, the optional decisionMode
field on the node determines how the results are combined:
decisionMode | Behavior |
|---|---|
fallback | Capabilities are evaluated in list order. The first definitive answer (true/false) determines the node status. On undefined, the next decision capability is evaluated; if none gives a definitive answer, the result is undefined. This is the default when decisionMode is not set. |
agreement | All decision capabilities MUST agree. All MUST be evaluated. On disagreement (e.g., one returns true, another returns false), the result is undefined. |
majority | Majority vote across all decision capabilities. All MUST be evaluated. On a tie, the result is undefined. |
Example:
"3": { "id": "551ff73a-66ce-48ca-b889-84bc63ce864c", "label": "Antragsteller volljährig", "decisionMode": "fallback", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_age >= 18" } }, { "id": "ruml:ai-query", "payload": { "model": "fast", "prompt": "Ist der Antragsteller volljährig?" } } ]}Rules:
decisionModeis an optional field on the node object (see Chapter 3.5.3), NOT in thecapabilitiesarray.decisionModeonly has an effect on leaf nodes. On parent nodes it MUST be ignored (Rule CAP-19CAP-19 A parser MUST acceptdecisionModeon a node withchildrenand MUST ignore it there.).- If a leaf node has exactly one
decisioncapability,decisionModeis irrelevant and SHOULD NOT be set. - With
fallback, the order of entries in thecapabilitieslist determines the evaluation order. Authors SHOULD place the preferred decision capability first.
Field Order
The capabilities list is ordered and the order is significant: capabilities are processed in list
order, and tools MUST preserve it when reading and writing a file and MUST NOT reorder the entries —
for example to sort them by capability ID (Rule CAP-20CAP-20 A tool that writes a file MUST NOT reorder the entries of a node's capabilities.). Reordering entries is a change to the
document, not a formatting choice — with decisionMode: "fallback" it changes which capability
decides the node.
Relationship to metadata at Node Level
The optional metadata field of a node (see Chapter 3.5.3)
is intended for non-structural information not associated with any capability. The
capabilities field is intended for declared, capability-bound extension data. Both fields MAY
be present simultaneously.
"4": { "id": "0eb360a6-626a-406d-89a1-9f434ced141b", "label": "Ausnahmetatbestand", "metadata": { "author": "Dr. Müller", "lastEditedBy": "validator-bot" }, "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_age >= 18" } } ]}