4.15 ruml:tree-reference
4.15 Capability ruml:tree-reference
Overview
| Property | Value |
|---|---|
| Capability ID | ruml:tree-reference |
| Scope | Root-Level (declaration only) + Node-Level |
Default required | false |
| Node-Level | payload.represents and payload.refersTo of the node’s ruml:tree-reference entry |
| Role | data |
This Capability lets a node point at a node of another RUML file — and with it at the subtree below that node. The typical case is a decision rulemap whose rules rest on a law that is itself available as a rulemap: the node for “articles of association notarised” points at the law’s node for § 2 (1) GmbHG instead of at the text of § 2 (1).
A node represents at most one node of another file and refers to any number of them. Neither is
evaluated: the referenced subtree does not influence the status of the node. To evaluate a
referenced subtree in place of a leaf, a node uses ruml:tree-include.
The referenced node brings its text with it: the law’s nodes have their own
ruml:text-reference anchors into the law’s text, so following a
tree reference leads to the provision and to its wording. The text is anchored in exactly one
place — the law’s file.
Distinction:
ruml:text-referenceanchors text elements of the same RUML file;ruml:tree-referencepoints at nodes of other RUML files.- Modular nodes reuse a subtree within the same file; a tree reference points into another file.
Root-Level Declaration
"capabilities": [ { "id": "ruml:tree-reference" }]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.). As for every capability, a file whose
nodes have ruml:tree-reference entries MUST declare it at the root (see
Chapter 4.3) (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.).
Node-Level: References
{ "id": "ruml:tree-reference", "payload": { "represents": { "uri": "https://rulemapping.org/rulemapping/gmbhg:2025-01-01#node/6e51c5a6-f7ff-43e1-b211-c70bd69937d7" }, "refersTo": [ { "uri": "https://rulemapping.org/rulemapping/gmbhg:2025-01-01#node/7791005b-3d30-455b-a538-6d96f04680d9" } ] }}| Field | Type | Required | Description |
|---|---|---|---|
represents | Object | MAY | The node of another RUML file this node stands for. |
refersTo | Array[Object] | MAY | Node anchors to nodes of other RUML files this node refers to. MUST contain at least one entry if present (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.). |
Validation rules:
- The payload MUST contain
represents,refersToor both, and MUST NOT contain other fields;representsand everyrefersToentry MUST have exactlyuri(Rule TREE-01TREE-01 The root entries ofruml:tree-referenceandruml:tree-includeMUST NOT have a payload. A node'sruml:tree-referencepayload MUST containrepresents,refersTo(with at least one entry) or both, andrepresentsand everyrefersToentry MUST have exactlyuri; a node'sruml:tree-includepayload MUST containuri. Both payloads MUST NOT contain other fields.). - Every
uriMUST be a node anchor (Rule TREE-02TREE-02 Everyuriof a tree reference or inclusion MUST be a node anchor<ruml-version-uri>#node/<id>; a same-document anchor (#node/…) is not one.). A same-document reference (#node/…) is not a node anchor — reuse within one file is what modular nodes are for. - The same
uriMUST NOT appear twice inrefersTo(Rule TREE-03TREE-03 The sameuriMUST NOT appear twice inrefersTo.). - The target node MUST exist in the referenced version of the file (
Rule TREE-04TREE-04 The target node of a node anchor MUST exist in the referenced version.).
Tree references MAY form cycles across files; they are not evaluated (Rule TREE-05TREE-05 A parser MUST accept ruml:tree-reference entries that form cycles across files.).
Node Anchors
A node anchor consists of the URI of one specific version of a RUML file, followed by a fragment that names a node inside it:
node-anchor = ruml-version-uri "#node/" uuidruml-version-uri = <absolute URI of an immutable RUML version: a published tag or a content digest>- Version: the RUML URI MUST identify one immutable version — a published version tag
(
…/gmbhg:2025-01-01) or a content digest (…/gmbhg@sha3-256:…). An anchor without a version MUST NOT appear in an exported or exchanged RUML 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.; see Working Anchors). - Node:
node/<uuid>addresses a node by itsidand, with it, the subtree below it. - One version per file: all node anchors of one RUML file that point into the same other RUML
file MUST use the same version of it (
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.). Moving to a new version of the law rewrites the version in the anchors; because node ids stay (see Stable Node Identity), the fragments stay the same.
The catalog at rulemapping.org provides such URIs (https://rulemapping.org/<org>/<name>:<tag>);
any other URI that identifies an immutable RUML version is equally valid.
ruml:tree-include uses the same node anchors.
Working Anchors
While RUML files are being written, they often link to each other before any of them is published. A
tool MAY therefore hold working anchors, which name the target file by its metadata.id
without a version and resolve to its current state:
working-anchor = "urn:uuid:" metadata-id "#node/" uuidurn:uuid:5b0e7c8d-2f41-4a9e-8c3b-1d6f0e2a7b95#node/6e51c5a6-f7ff-43e1-b211-c70bd69937d7
Working anchors exist only in a tool’s working state. When a RUML file is exported or exchanged, the
tool MUST replace every working anchor with a node anchor to a published version of its target;
if a target has no published version, the export MUST fail. A working anchor stays valid while
the target file is edited, as long as the target node keeps its id.
Resolution and Display
A tool resolves a node anchor by loading the referenced version of the file (from a
bundled file first) and selecting the node whose id equals the fragment’s
<id>. That node and its subtree are the referenced content.
- Texts: the referenced nodes keep their own
ruml:text-referenceanchors, which resolve within the referenced file. A tool SHOULD show the texts of the referenced subtree together with it; the referencing node needs no text anchors of its own for them. It MAY have its ownruml:text-referenceanchors in addition (Rule TREE-07TREE-07 A parser MUST accept a node that hasruml:text-referenceanchors besides aruml:tree-referenceentry.). - Display: a tool MAY show the referenced subtree read-only at the referencing node. The referenced subtree is never copied into the referencing file.
Bundling for Export
A RUML file whose node anchors point into other RUML files can be exported as a container
(Chapter 7) that also holds those files, each with its version URI in
the manifest entry’s uri field
(Bundled RUML Files). A parser MUST
resolve a node anchor against the bundled RUML file whose manifest uri equals the anchor’s RUML
URI before fetching it from elsewhere. Nothing is copied into the referencing file; the container’s
integrity and signature layers cover the bundled files like any other file.
Stable Node Identity
Node anchors name node id values, so they survive a new version of the referenced file only if its
nodes keep their ids.
- A rulemap that other files may reference SHOULD keep a node’s
idunchanged across versions as long as the node stands for the same thing. - A rulemap that represents a law SHOULD use, as the
idof a node that anchors an element of its own text, that element’sGUID— provided it is a lowercase UUID v4 and unique among the file’s node ids. Node identity then follows text identity, which survives renumbering.
Behavior for modular nodes: a tree reference on a modular node (modular: true) applies to
all instantiations, regardless of where the node appears in the rule tree.