Skip to content
RUMLRUML

Open Format for Digital Law

4.15 ruml:tree-reference

4.15 Capability ruml:tree-reference

Overview

PropertyValue
Capability IDruml:tree-reference
ScopeRoot-Level (declaration only) + Node-Level
Default requiredfalse
Node-Levelpayload.represents and payload.refersTo of the node’s ruml:tree-reference entry
Roledata

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-reference anchors text elements of the same RUML file; ruml:tree-reference points 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"
}
]
}
}
FieldTypeRequiredDescription
representsObjectMAYThe node of another RUML file this node stands for.
refersToArray[Object]MAYNode 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, refersTo or both, and MUST NOT contain other fields; represents and every refersTo entry MUST have exactly uri (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.).
  • Every 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 same-document reference (#node/…) is not a node anchor — reuse within one file is what modular nodes are for.
  • The same uri MUST NOT appear twice in refersTo (Rule TREE-03TREE-03 The same uri MUST NOT appear twice in refersTo.).
  • 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/" uuid
ruml-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 its id and, 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/" uuid

urn: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-reference anchors, 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 own ruml:text-reference anchors in addition (Rule TREE-07TREE-07 A parser MUST accept a node that has ruml:text-reference anchors besides a ruml:tree-reference entry.).
  • 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 id unchanged across versions as long as the node stands for the same thing.
  • A rulemap that represents a law SHOULD use, as the id of a node that anchors an element of its own text, that element’s GUID — 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.

Conformance tests