4.1 Concept
4.1 Concept
What Capabilities Provide
The RUML core structure (Chapters 1–3) serves to represent regulations and laws as machine-readable decision trees — with nodes, operators, legal references, and metadata. This structure is complete and stable, but intentionally passive: it describes what should be evaluated, not how the evaluation is performed.
Capabilities fulfill two roles:
1. Decision-Making Ability — They make a rulemap executable. They define:
- What decisions are based on — e.g., typed data points (
ruml:datapoints), data-based queries (ruml:query), AI models (ruml:ai-query) - How decisions are made — expressions, prompts, external bindings
- What happens next — triggered actions (
ruml:actions) - What the decision relies on — normative texts (
ruml:text-reference), nodes of other rulemaps (ruml:tree-reference,ruml:tree-include), context materials (ruml:context)
2. Extensibility — The capabilities system additionally provides a controlled, interoperable mechanism for declaring and transporting additional information without modifying the core structure:
- Domain-specific metadata relevant only to a particular legal system
- Experimental extensions not yet part of the open specification
- Third-party annotations maintained alongside the RUML core
Two-Layer Model
RUML follows a deliberate two-layer model:
| Layer | Content | Purpose |
|---|---|---|
| RUML Core (Chapters 1–3) | Decision tree, operators, labels, metadata | Structural representation of regulations and laws; stable, passive, certifiable |
| RUML + Capabilities (Chapter 4) | ruml:datapoints, ruml:query, ruml:ai-query, ruml:actions, ruml:text-reference, ruml:tree-reference, ruml:tree-include, ruml:context and proprietary extensions | Decision-making ability, execution logic, materials, and third-party extensions |
The RUML Core is structurally self-contained: a RUML file without capabilities contains all information needed to represent the rule structure and its normative-text anchoring. Applying a rulemap to a concrete case — supplying input data, evaluating leaf-node conditions, triggering actions — is enabled by capabilities (Chapter 4) and the runtime environment.
The Two Delivery Modes
Capability data can be introduced into a RUML document ecosystem in two ways:
Inline Mode (embedded)
The capability is declared in the capabilities array of the RUML file, and the extension data is
stored directly as a capabilities field on the affected nodes or as part of the declaration at the
root level.
{ "$format": "RUML", "$specVersion": "1.0", "capabilities": [ { "id": "ruml:query" }, { "id": "ruml:datapoints", "payload": { "data": { "dp_age": { "name": "Alter des Antragstellers", "type": "integer", "binding": { "type": "input" } }, "dp_income": { "name": "Jahreseinkommen", "type": "number", "binding": { "type": "input" } } } } } ], "metadata": { "id": "ec36948d-fbb2-4815-985a-bd5e9375d934", "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", "operator": "AND", "label": "Kreditwürdigkeit prüfen", "children": ["2", "3"] }, "2": { "id": "551ff73a-66ce-48ca-b889-84bc63ce864c", "label": "Mindestalter erfüllt", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_age >= 18" } } ] }, "3": { "id": "42d9431d-b7db-404f-bdf9-7ecdde505cce", "label": "Einkommen ausreichend", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_income >= 30000" } } ] } } }}Sidecar Mode (RUML-EXT)
The extension data is stored in a separate .ruml-ext file linked to the original RUML file via a
$base reference (UUID + hash).
Fail-Fast on Unknown Capabilities
Each capability declares via required whether it is mandatory for correct processing:
required: true— The parser MUST support this capability. If it does not recognize it, it MUST reject the file (Rule CAP-01CAP-01 A parser MUST reject a file that declares a capability withrequired: truethat the parser does not implement, and MUST NOT process such a file partially.).required: false— The parser MUST accept the file and ignore this capability (Rule CAP-02CAP-02 A parser MUST accept a file that declares a capability it does not implement withrequired: falseor withoutrequired, and MUST ignore thepayloadand the node-level entries of that capability.). It SHOULD emit a warning.
A parser MUST NOT silently accept a file with an unknown required: true capability
(Rule CAP-01CAP-01 A parser MUST reject a file that declares a capability with required: true that the parser does not implement, and MUST NOT process such a file partially.). Silently discarding extension data would lead to seemingly correct but incomplete
processing.
Capability Roles
Each capability has exactly one role, specified in the respective capability specification. The role determines
- whether a capability can occur once or multiple times on a node,
- how the capability is evaluated, and
- how the result affects the rulemap.
The role of each official ruml: capability is defined in this specification.
ruml:draft/ and reverse-domain capabilities are extension points of this specification. Their role
is defined by the parser and evaluator that implement them, not by this specification.
The root-level entry of such a capability MUST declare the role the rulemap expects in its role
field (see Chapter 4.2; Rule CAP-03CAP-03 The root entry of a ruml:draft/ or reverse-domain capability MUST declare role.). The declaration makes the role
visible in the file and lets tools check it:
- A parser that implements the capability MUST reject the file if the declared role differs from the
implemented one (
Rule CAP-04CAP-04 A parser that implements aruml:draft/or reverse-domain capability MUST reject the file if the declaredrolediffers from the role it implements.). - A parser that does not implement the capability applies the role-based rules below to the declared role.
An official ruml: capability MUST NOT declare role (Rule CAP-05CAP-05 The root entry of an official ruml: capability MUST NOT declare role.).
data
- Restrictions: None
- Multiplicity: Each id of a
datacapability MUST NOT occur more than once on a node (Rule CAP-06CAP-06 On one node, a capability with thedatarole MUST NOT have more than one entry; a parser MUST accept several entries of a capability with thedecisionorreactionrole.). - Examples:
ruml:datapoints,ruml:text-reference,ruml:tree-reference,ruml:context
Provides input data or materials, but does not output directly.
decision
- Restrictions: Capabilities with the
decisionrole MUST NOT be applied to nodes with children (Rule CAP-07CAP-07 An entry of a capability with thedecisionrole MUST NOT appear on a node withchildren.). - Multiplicity: IDs of a
decisioncapability, MAY occur multiple times on each node (Rule CAP-06CAP-06 On one node, a capability with thedatarole MUST NOT have more than one entry; a parser MUST accept several entries of a capability with thedecisionorreactionrole.). - Examples:
ruml:query,ruml:ai-query,ruml:tree-include
Determines the status of a leaf node. It MUST return true, false, or undefined. If a leaf node
contains multiple decision capabilities, the decisionMode field on the node determines how the
results are combined (see Chapter 4.3).
combiner
- Restrictions: Capabilities with the
combinerrole MUST NOT be applied to a node whose operator is notDELEGATED(Rule CAP-08CAP-08 An entry of a capability with thecombinerrole MUST NOT appear on a node whoseoperatoris notDELEGATED.). - Multiplicity: A node with a
DELEGATEDoperator and children MUST have exactly one capability of rolecombiner(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).). - Examples:
ruml:expression
Determines the status of a parent node based on the node status of its children. It can be used in
cases where the other built-in operators are not enough. It MUST return true, false, or
undefined.
reaction
- Restrictions: None
- Multiplicity: IDs of a
reactioncapability, MAY occur multiple times on each node (Rule CAP-06CAP-06 On one node, a capability with thedatarole MUST NOT have more than one entry; a parser MUST accept several entries of a capability with thedecisionorreactionrole.). - Examples:
ruml:actions
A capability has exactly one role. A provider that wants to offer the same logic as a leaf
decision and as a combiner — such as one expression language usable in both places — registers
two capability ids, one per role. The role is documented in the overview table of the capability
specification.
Signing of Capabilities
When capabilities are provided inline in the capabilities array, they are part of the file and
are included when signing. A RUML file with inline capabilities can thus be fully certified. The
signature protects both the core structure and the extended artifacts.