Skip to content
RUMLRUML

Open Format for Digital Law

4.16 ruml:tree-include

4.16 Capability ruml:tree-include

Overview

PropertyValue
Capability IDruml:tree-include
ScopeRoot-Level (declaration only) + Node-Level
Default requiredfalse
Node-Levelpayload.uri of the node’s ruml:tree-include entry
Roledecision

This Capability makes a leaf node a placeholder for the subtree of a node of another RUML file: the referenced subtree is evaluated in place of the leaf, and its status becomes the status of the leaf.

It complements ruml:tree-reference, which only points at nodes of other files. Both use the same node anchors; they are two capabilities because a capability has exactly one role (see Chapter 4.1).

Why “include”: the name describes the relation from the including node’s view — the referenced subtree is part of this rulemap at exactly this position without being copied, like Akoma Ntoso componentRef, XInclude or DITA conref.

Distinction from modular nodes: modular nodes reuse a subtree within the same file. ruml:tree-include evaluates the referenced subtree like an instance of a modular node whose definition lives in another file.

Root-Level Declaration

"capabilities": [
{
"id": "ruml:tree-include"
}
]

The root-level entry MUST NOT have a payload (Rule TREE-01TREE-01 The root entries of ruml:tree-reference and ruml:tree-include MUST NOT have a payload. A node's ruml:tree-reference payload MUST contain represents, refersTo (with at least one entry) or both, and represents and every refersTo entry MUST have exactly uri; a node's ruml:tree-include payload MUST contain uri. Both payloads MUST NOT contain other fields.).

Node-Level: The Included Node

{
"id": "ruml:tree-include",
"payload": {
"uri": "https://rulemapping.org/rulemapping/gmbhg:2025-01-01#node/6e51c5a6-f7ff-43e1-b211-c70bd69937d7"
}
}
FieldTypeRequiredDescription
uriStringMUSTA node anchor to the included node: <ruml-version-uri>#node/<id>.

Validation rules:

  • The payload MUST contain uri and MUST NOT contain other fields (Rule TREE-01TREE-01 The root entries of ruml:tree-reference and ruml:tree-include MUST NOT have a payload. A node's ruml:tree-reference payload MUST contain represents, refersTo (with at least one entry) or both, and represents and every refersTo entry MUST have exactly uri; a node's ruml:tree-include payload MUST contain uri. Both payloads MUST NOT contain other fields.), and uri MUST be a node anchor (Rule TREE-02TREE-02 Every uri of a tree reference or inclusion MUST be a node anchor <ruml-version-uri>#node/<id>; a same-document anchor (#node/…) is not one.).
  • A node with ruml:tree-include MUST NOT have children (Rule CAP-07CAP-07 An entry of a capability with the decision role MUST NOT appear on a node with children.).
  • A node with ruml:tree-include MUST NOT have represents in its ruml:tree-reference (Rule TREE-08TREE-08 A node with ruml:tree-include MUST NOT have represents in its ruml:tree-reference.): a node that includes another node already stands for it.
  • The node anchor rules of Chapter 4.15 apply: one immutable version, the same version for all node anchors into one file (Rule TREE-06TREE-06 A node anchor MUST name an immutable RUML version; a file that is exported or exchanged MUST NOT contain an anchor without a version. All node anchors of a file into the same other RUML file MUST use the same version of it.), and the target node exists in that version (Rule TREE-04TREE-04 The target node of a node anchor MUST exist in the referenced version.).
  • Inclusions MUST NOT form a cycle across files (Rule TREE-09TREE-09 Inclusions MUST NOT form a cycle across files, directly or through further files.): file A includes a node of B, and B includes a node of A — directly or through further files.

Including Several Subtrees

To include several subtrees, a rulemap uses several placeholder nodes. The tree then defines everything the combination needs: the order is the child order, the combination is the parent’s operator, a negation is a parent node with a NOT_… operator (see Chapter 3.6), and every include has its own label, explanation, text references and result.

"Company validly founded" AND
├── "Articles of association notarised" include → gmbhg:2025-01-01#node/6e51…
├── "Share capital at least EUR 25,000" include → gmbhg:2025-01-01#node/7791…
└── "Entered in the commercial register" (own logic)

As with modular nodes, reuse is visible as a node in the tree, not as hidden extra children.

Evaluation

A tool resolves the included node (see Resolution and Display), evaluates it with its subtree under the rules of the referenced file, and uses the resulting status as the result of the capability. If the leaf has further decision capabilities, decisionMode combines their results (see Chapter 4.3).

Not defined in this version: how the included subtree obtains its inputs — the data points and questions its leaves evaluate — is not defined in this version of the specification. Under consideration are inputs shared with the including file by data point id, inputs namespaced per referenced file, and an explicit binding per include.

A tool that cannot evaluate an inclusion — because it does not support ruml:tree-include, or because the referenced version or node cannot be loaded — MUST use undefined as its result (see Chapter 5.0); it MUST NOT treat the node as fulfilled.

Behavior for modular nodes: an inclusion on a modular node (modular: true) applies to all instantiations.

Conformance tests