Skip to content
RUMLRUML

Open Format for Digital Law

4.12 ruml:text-reference

4.12 Capability ruml:text-reference

Overview

PropertyValue
Capability IDruml:text-reference
ScopeRoot-Level (data) + Node-Level
Default requiredfalse
Node-Levelpayload.refs of the node’s ruml:text-reference entry
Roledata

This Capability links nodes with normative texts — laws, regulations, technical standards, administrative directives, and other regulatory frameworks.

A RUML file carries its texts in the root data object — as plain text or as structured RUML Text. Node-level anchors are local: they point only into the texts of the same RUML file. A rulemap that relies on a law kept in another RUML file does not anchor into that file’s text; it references the law’s nodes (ruml:tree-reference), which have their own anchors.

The node’s norm (represents): among its anchors, a node MAY mark the single text it represents — the norm the rule implements (see Node-Level).

Distinction from ruml:context: ruml:context (Chapter 4.11) contains supporting, informative materials (court decisions, commentaries, examples) as well as the subject matter under examination. ruml:text-reference contains normative foundational texts on which decision rules are based.

Use Cases

  • Linking nodes with underlying norms and regulatory frameworks
  • Documentation of legal bases for audit trails
  • Carrying a complete law as structured text in the RUML file that represents it
  • Linking every node of that law’s rulemap to the element of the text it represents
  • Multilingual texts for international applications

Root Level: Text Entries

Texts are provided via the ruml:text-reference Capability — either inline in the capabilities array of the RUML file or via a RUML-EXT sidecar file (Chapter 4.5):

{
"$format": "RUML",
"$specVersion": "1.0",
"capabilities": [
{
"id": "ruml:text-reference",
"payload": {
"data": {
"text_main": {
"title": "Sozialgesetzbuch (SGB) Zwölftes Buch (XII) – Sozialhilfe",
"uri": "eli/bund/bgbl-1/2003/s3023/2026-07-30/1/deu",
"timestamp": "2026-10-09T00:00:00Z",
"digest": "sha3-256:87464fc40b2e11c817467dffbc6c57c16d1611e132d4ae8d431f3f755357198f",
"source": {
"uri": "https://testphase.rechtsinformationen.bund.de/v1/legislation/eli/bund/bgbl-1/2003/s3023/2026-07-30/1/deu/regelungstext-verkuendung-1.xml"
},
"content": {
"type": "akomaNtoso",
"attrs": {
"xmlns": "http://Inhaltsdaten.LegalDocML.de/1.8.2/"
},
"content": [/* ... */]
}
},
"text_bgb_823": {
"title": "§ 823 BGB – Schadensersatzpflicht",
"uri": "/akn/de/act/1896-08-18/bgb#sec_823__subsec_1",
"timestamp": "2024-01-01T00:00:00Z",
"status": "inForce",
"text": "Wer vorsätzlich oder fahrlässig das Leben, den Körper, die Gesundheit, die Freiheit, das Eigentum oder ein sonstiges Recht eines anderen widerrechtlich verletzt, ist dem anderen zum Ersatz des daraus entstehenden Schadens verpflichtet.",
"validFrom": "2002-01-01T00:00:00Z",
"language": "de"
},
"text_3f2c9a1e4b7d4e0f9a6c1b2d3e4f5a6b": {
"title": "Benutzungssatzung der Stadtbibliothek",
"timestamp": "2026-10-10T09:00:00Z",
"digest": "sha3-256:b146f781bafdee78f9e68475fca93da37cf68d3559cd1c5f6e82ab3cef9c2638",
"content": {
"type": "akomaNtoso",
"attrs": {
"xmlns": "http://Inhaltsdaten.LegalDocML.de/1.8.2/"
},
"content": [/* ... */]
}
}
}
}
}
],
"metadata": {/* ... */},
"rulemap": {/* ... */}
}

Key Convention: The keys in the data object (e.g., text_main) serve as unique identifiers. Keys MUST match the pattern [a-z_][a-z0-9_]* (Rule TXT-02TXT-02 A text key MUST match the pattern [a-z_][a-z0-9_]*.). A separate id field is not required. Anchors embed the key, so a key MUST NOT change once anchors may point at it (Rule TXT-03TXT-03 A text key MUST NOT change once anchors may point at it, and the GUID of an element MUST NOT change; a tool that imports a new version of a text MUST carry the GUID of every element it matches forward.); tools that generate keys SHOULD use text_ followed by the 32 hexadecimal digits of a UUID without hyphens (text_3f2c9a1e4b7d4e0f9a6c1b2d3e4f5a6b) and SHOULD NOT derive keys from titles. Each official language version of a text is its own entry (e.g., text_de, text_fr).

Required Fields

FieldTypeDescription
titleStringMUST give the human-readable title of the text, e.g. for lists and catalogs (Rule TXT-04TXT-04 A text entry MUST have title and timestamp, and status unless it has content.).
timestampDateTimeMUST specify the time of recording as an RFC 3339 date-time (Rule TXT-04TXT-04 A text entry MUST have title and timestamp, and status unless it has content., Rule TXT-05TXT-05 In a text entry, timestamp and validFrom MUST be RFC 3339 date-times, url a URI and language an ISO 639-1 code.).
statusEnumMUST specify the status (see Status Values) unless the entry has content; with content, the status follows from the text’s own metadata (Rule TXT-04TXT-04 A text entry MUST have title and timestamp, and status unless it has content.).

Optional Fields

FieldTypeDescription
uriStringMUST identify the text when it is published by an authority or another external source (see URI Convention); omitted for texts written in this RUML file.
typeEnumMAY specify the embedding type: embedded, container, url, external. Default: embedded. external is deprecated (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.).
textStringMAY contain the text as plain text. An entry MUST NOT carry both text and content (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced., Rule TXT-07TXT-07 A text entry MUST NOT have both text and content; an embedded entry with status inForce MUST have a non-empty text or a content.).
contentObjectMAY contain the text as RUML Text. Requires digest (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced., Rule TXT-08TXT-08 A text entry with content MUST have digest, sha3-256: followed by 64 lowercase hexadecimal digits.).
digestStringMUST be present with content: sha3-256: followed by the hex SHA3-256 of the canonical form of content (Rule TXT-08TXT-08 A text entry with content MUST have digest, sha3-256: followed by 64 lowercase hexadecimal digits., Rule TXT-09TXT-09 digest MUST equal the SHA3-256 hash of the UTF-8 bytes of the RFC 8785 form of content.).
sourceObjectSHOULD be present with content: provenance of the text — uri of the source document it was imported from, optional digest of the archived source, optional terms (URI of the source’s reuse terms, where the source attaches any).
urlStringMUST contain the URL when type: "url". MUST be a valid URI format (Rule TXT-05TXT-05 In a text entry, timestamp and validFrom MUST be RFC 3339 date-times, url a URI and language an ISO 639-1 code., Rule TXT-10TXT-10 A text entry with type url, container or external MUST have url, containerPath or ref respectively.).
containerPathStringMUST specify the path in the container when type: "container". MUST start with .texts/ (Rule TXT-10TXT-10 A text entry with type url, container or external MUST have url, containerPath or ref respectively., Rule TXT-11TXT-11 The containerPath of a text entry MUST start with .texts/.).
refStringMUST contain a symbolic reference when type: "external" (Rule TXT-10TXT-10 A text entry with type url, container or external MUST have url, containerPath or ref respectively.).
versionStringMAY specify the version (e.g., "Fassung vom 1.1.2024") (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.).
validFromDateTimeMAY specify the validity start date. MUST be an RFC 3339 date-time (Rule TXT-05TXT-05 In a text entry, timestamp and validFrom MUST be RFC 3339 date-times, url a URI and language an ISO 639-1 code., Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.).
validUntilDateTimeMAY specify the validity end date. MUST be > validFrom if present (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced., Rule TXT-12TXT-12 When a text entry has both, validUntil MUST be later than validFrom.).
languageStringMAY specify the language. MUST conform to ISO 639-1 format (e.g., "de", "en") (Rule TXT-05TXT-05 In a text entry, timestamp and validFrom MUST be RFC 3339 date-times, url a URI and language an ISO 639-1 code., Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.).
isReferencedBooleanMAY indicate whether this entry is referenced by nodes. Default: true (Rule TXT-06TXT-06 A parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.).

When an entry has content, the fields status, validFrom, validUntil, language and version SHOULD be omitted; if present, they MUST agree with the text’s own metadata (Rule TXT-13TXT-13 In a text entry with content, status, validFrom, validUntil, language and version MUST agree with the metadata of the text itself.).

URI Convention

The uri of a text entry identifies a text that exists outside the RUML file — preferably by its official identifier. A text written in the RUML file itself has no uri; it is identified by the file and its entry key. The uri is not used to address elements inside the text; that is the job of anchors.

FormatExampleNotes
European Legislation Identifier (ELI)eli/bund/bgbl-1/2003/s3023/2026-07-30/1/deu, http://data.europa.eu/eli/reg/2016/679/ojPreferred where the authority issues ELIs
Akoma Ntoso (AKN)/akn/de/act/1900-08-18/bgbInternational standard for legal documents
STOP (NL)/akn/nl/act/2024/gst-2024-123Dutch legal documents
Gesetze-im-Internethttps://www.gesetze-im-internet.de/bgb/__823.htmlAcceptable for German law without official identifier

The RUML spec does not mandate a specific URI scheme. Authors SHOULD use the official identifier where one exists.

Embedding Types (type)

TypeDescriptionUsage
embeddedDirectly in the RUML file, as text or contentText of any length — from individual sections up to the complete text of a law
containerIn the RUML container (ZIP)Original/binary formats (e.g., PDF)
urlExternal URLPublic portals (e.g., gesetze-im-internet.de)
externalSymbolic reference (deprecated)Superseded by RUML files that carry the text themselves

Note on complete statutes: a rulemap that represents a law (documentType: "law") carries the full statutory text as an embedded entry, preferably as content in RUML Text — there is NO length limit. Other rulemaps reference that law’s nodes instead of copying the text.

Note on url: The tool SHOULD fetch and cache the content as needed. The URL SHOULD point to a stable, versioned source.

Note on external: The tool MUST resolve the symbolic reference (ref) to a concrete data source. Configuration is done in the tool settings, NOT in the RUML file. New files SHOULD reference the RUML file that carries the text instead.

The complete container specification (ZIP structure, manifest, directory conventions) is defined in Chapter 7.

Status Values

StatusDescriptionUsage
draftDraftNot yet enacted
proposedProposedIntroduced drafts, under deliberation
enactedEnactedAdopted but not yet in force
inForceIn forceCurrently valid norm
amendedAmendedReplaced by a newer version but still valid for legacy cases
repealedRepealedNo longer in force

Validation rule: For status: "inForce" and type: "embedded" (the default), the entry MUST have a non-empty text or a content (Rule TXT-07TXT-07 A text entry MUST NOT have both text and content; an embedded entry with status inForce MUST have a non-empty text or a content.). Entries with any other status MAY omit both.


RUML Text

RUML Text is the structured form of a legal text: an Akoma Ntoso XML document written as JSON, without loss. It is part of the RUML format, not a file format of its own: it exists only in a text entry’s content, and its rules are those of the file’s $specVersion. XML remains the format for exchange and validation: Akoma Ntoso documents, including those of national dialects such as LegalDocML.de, convert into RUML Text and back mechanically (Conversion).

Structure

"content": {
"type": "akomaNtoso",
"attrs": {
"xmlns": "http://Inhaltsdaten.LegalDocML.de/1.8.2/"
},
"content": [
{
"type": "act",
"attrs": {
"name": "regelungstext"
},
"content": [
{
"type": "body",
"content": [
{
"type": "article",
"attrs": {
"eId": "art-z1",
"GUID": "0b1e9e8a-2c55-4f5f-9a3e-6d1c7b2a4e01"
},
"content": [
{
"type": "num",
"content": ["§ 1"]
},
{
"type": "heading",
"content": ["Aufgabe der Sozialhilfe"]
},
{
"type": "paragraph",
"attrs": {
"eId": "art-z1_abs-z",
"GUID": "5d8f3c21-7a64-4c0b-8e2f-1a9b6c3d7e02"
},
"content": [
{
"type": "num"
},
{
"type": "content",
"content": [
{
"type": "p",
"content": [
"Aufgabe der Sozialhilfe ist es, den Leistungsberechtigten die Führung eines Lebens zu ermöglichen, das der Würde des Menschen entspricht.",
{
"type": "marker",
"attrs": {
"eId": "art-z1_abs-z_inhalt-n1_text-n1_marker-n1",
"GUID": "9a7c2e14-3b58-4d6f-a1e0-4c2b8d5f6a03",
"refersTo": "satzende"
}
},
" Die Leistung soll sie so weit wie möglich befähigen, unabhängig von ihr zu leben; darauf haben auch die Leistungsberechtigten nach ihren Kräften hinzuarbeiten.",
{
"type": "marker",
"attrs": {
"eId": "art-z1_abs-z_inhalt-n1_text-n1_marker-n2",
"GUID": "e27b9d03-1c4a-4f86-b5d2-7a0c9e3f1b24",
"refersTo": "satzende"
}
},
" Zur Erreichung dieser Ziele haben die Leistungsberechtigten und die Träger der Sozialhilfe im Rahmen ihrer Rechte und Pflichten zusammenzuwirken.",
{
"type": "marker",
"attrs": {
"eId": "art-z1_abs-z_inhalt-n1_text-n1_marker-n3",
"GUID": "55a21fb5-d00e-41c1-91a2-38eda90f21e0",
"refersTo": "satzende"
}
}
]
}
]
}
]
}
]
}
]
}
]
}
]
}
  • Elements: every element of the XML document is a node {type, attrs?, content?}. type is the element name and attrs holds its attributes with string values, both named as in the XML. content holds the children in document order; character data is a plain JSON string.
  • Exact tree: wrapper elements such as content, intro or num are nodes like any other. All character data is kept, including whitespace between elements. Adjacent strings MUST be merged into one (Rule TXT-14TXT-14 In content, a content array MUST NOT contain two adjacent strings.).
  • Root: the root object is the Akoma Ntoso root element. It MUST have type, attrs and content (Rule TXT-15TXT-15 The root of content MUST have type, attrs and content, and MUST declare the namespace of its dialect as its default namespace (attrs.xmlns).).
  • Namespaces: namespace declarations are attributes and stay where the XML has them. The root MUST declare the namespace of its dialect as the default namespace (xmlns), so the dialect’s elements carry no prefix; no other element redeclares xmlns (Rule TXT-15TXT-15 The root of content MUST have type, attrs and content, and MUST declare the namespace of its dialect as its default namespace (attrs.xmlns)., Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.). Names from other namespaces, such as the ris: metadata of LegalDocML.de, keep their prefix; the prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor (Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.). Elements and attributes of any namespace MUST be kept, also when a tool does not understand them (Rule TXT-17TXT-17 A tool that writes RUML Text MUST keep the elements and attributes of every namespace, including those it does not understand, and MUST NOT add sentence markers that the source does not contain.).
  • Document types: the root may hold any Akoma Ntoso document type — act, bill, amendment, judgment, documentCollection and others.

Conversion

From XML. Each element becomes a node with its name as type, its attributes (namespace declarations included) as attrs and its children as content. Character data, CDATA sections and resolved entity and character references become strings. Not represented are the XML declaration, the document type declaration, comments, processing instructions and the attribute xsi:schemaLocation: they carry no part of the legal text. An element MUST NOT have the attribute xsi:schemaLocation (Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.). Where the source binds the dialect’s namespace to a prefix (LegalDocML.de documents use akn:), the importer removes the prefix from the names of the elements in that namespace and declares the namespace with xmlns on the root; it keeps the xmlns:<prefix> declaration only while attributes still use the prefix.

To XML. Each node becomes an element named type with the attributes in attrs and its content in order. Strings become character data, with &, < and > escaped, and in attribute values also ", tab, line feed and carriage return. An exporter MAY write an XML declaration and the schema references its dialect uses (for LegalDocML.de, xsi:schemaLocation on the root and an xml-model processing instruction for the Schematron).

Round trip. An XML document converted to RUML Text and back equals the original under Canonical XML 2.0, except for the parts not represented and a prefix the importer removed.

Dialects

The root’s default namespace names the Akoma Ntoso dialect of the text and its version. Converted to XML, a text MUST be valid against the schemas of its dialect (Rule TXT-18TXT-18 Converted to XML, content MUST be valid against the schemas of the dialect its root namespace names; a fragment MUST be valid where it stands in a complete document.). A text MAY be a fragment that omits parts its dialect requires, such as the meta block of a text generated by a tool; every element it does contain MUST then be valid where it stands in a complete document of the dialect (Rule TXT-18TXT-18 Converted to XML, content MUST be valid against the schemas of the dialect its root namespace names; a fragment MUST be valid where it stands in a complete document.). RUML restates none of the dialect’s rules: numbering, eId formation and citation are defined by the dialect and checked by its schemas.

DialectNamespace (xmlns)Schemas
Akoma Ntoso 3.0 (OASIS)http://docs.oasis-open.org/legaldocml/ns/akn/3.0XSD
LegalDocML.de 1.8.2 (German federal law)http://Inhaltsdaten.LegalDocML.de/1.8.2/XSD, Schematron

Element Identity: GUID

Every element that carries an eId MUST also carry a GUID (Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.). The GUID is the element’s lasting identity, and anchors point at it; the eId is its readable designation in the current version, formed from the numbering by the rules of the text’s dialect (for LegalDocML.de: Schematron rules SCH-00430 to SCH-00450), and changes when the text is renumbered.

  • Value: MUST be a lowercase UUID (RFC 9562, Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.), assigned when the element is created. A text imported from a source that carries GUID values (LegalDocML.de requires one on every element) keeps them.
  • Uniqueness: within one text entry, a GUID MUST be unique (Rule TXT-16TXT-16 In content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.). A copied element is a new element and gets a new GUID.
  • Stability: a GUID MUST NOT change — not in published versions and not in drafts, because anchors in this file, and references from other RUML files to the nodes anchored here, may already rely on it (Rule TXT-03TXT-03 A text key MUST NOT change once anchors may point at it, and the GUID of an element MUST NOT change; a tool that imports a new version of a text MUST carry the GUID of every element it matches forward.). Renumbering changes eId values only.
  • Across versions: a new version of a text keeps the GUID of every element that continues and gives new elements new ones. Where a source issues new GUID values for each version, the importer MUST carry forward the GUID of each element it matches to the previous version (Rule TXT-03TXT-03 A text key MUST NOT change once anchors may point at it, and the GUID of an element MUST NOT change; a tool that imports a new version of a text MUST carry the GUID of every element it matches forward.).
  • Languages: each language version is its own text entry with its own GUID values; RUML defines no identity across language versions.

Example: ”§ 3” is created with eId art-z3 and GUID 7c1e9a52-…. A new § 2 is inserted before it; the element becomes ”§ 4” with eId art-z4 — its GUID stays 7c1e9a52-…, so every anchor to it still finds it, and citations show the current ”§ 4”.

Sentences

Where the source marks the end of a sentence with a marker element whose refersTo is satzende (as LegalDocML.de does), the marker’s GUID identifies the sentence ending at that marker; an anchor to it addresses that sentence. Tools MUST NOT add sentence markers that the source does not contain (Rule TXT-17TXT-17 A tool that writes RUML Text MUST keep the elements and attributes of every namespace, including those it does not understand, and MUST NOT add sentence markers that the source does not contain.). Texts without sentence markers can be anchored down to their smallest marked element (e.g., a subsection or item).

Digest

The digest of a text entry is sha3-256: followed by the lowercase hex SHA3-256 hash of the UTF-8 bytes of the RFC 8785 (JSON Canonicalization Scheme) form of content. A parser SHOULD verify it before relying on the text.

Provenance

source records where the text was imported from; source.terms points to the source’s reuse terms where the source attaches any (for example an attribution requirement).

RUML defines no plain-text form of RUML Text. Tools that need plain text derive it from the tree themselves.


Node-Level: Anchors

Nodes point at the texts of their own RUML file with anchors in the refs list of their node-level ruml:text-reference entry. An anchor names a text entry by its key and, optionally, one element of its RUML Text by the element’s GUID.

{
"id": "ruml:text-reference",
"payload": {
"refs": [
{
"id": "text_main",
"element": "9a7c2e14-3b58-4d6f-a1e0-4c2b8d5f6a03",
"type": "represents"
},
{
"id": "text_main",
"element": "e27b9d03-1c4a-4f86-b5d2-7a0c9e3f1b24",
"type": "refers-to"
},
{
"id": "text_bgb_823",
"type": "refers-to"
}
]
}
}
FieldTypeRequiredDescription
refsArray[Object]MUSTThe node’s anchors; at least one (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).
idStringMUSTKey of a text entry in this file’s own data object (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).
elementStringMAYGUID of an element of the entry’s RUML Text — an article, a paragraph, a list item, a sentence marker. Without element the anchor addresses the whole text (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).
typeEnumMUSTrepresents: the norm the node implements — the text the rule turns into a decision. refers-to: a text the node relies on without implementing it, such as a definition or a cross-reference (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).

Validation rules:

  • refs MUST contain at least one anchor (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).
  • A node MUST NOT have more than one anchor of type represents (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).
  • Each id MUST exist as a key in the data object of this file’s ruml:text-reference Capability (Rule TXT-19TXT-19 Every id of an anchor in the refs of a node's ruml:text-reference entry, and every id in inputs.texts of a ruml:ai-query, MUST be a key of the data of ruml:text-reference.).
  • An element MUST be the GUID of an element in that entry’s content; an entry without content can only be anchored as a whole (Rule TXT-20TXT-20 The element of an anchor MUST be the GUID of an element in the content of the entry its id names; an anchor into an entry without content MUST NOT have element.).
  • Anchors MUST be unique — the same id, element and type MUST NOT appear twice (Rule TXT-01TXT-01 The payload of a node's ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.).

Anchors never leave their RUML file, so they carry no file or version: when the file moves to a new version of its text, the anchors stay as they are because GUID values are stable. Character ranges and text-quote selectors are not supported; the finest addressable unit is an element with a GUID.

Behavior for modular nodes: a modular node (modular: true) always represents the same norm — its anchors apply to all instantiations, regardless of where the node appears in the rule tree.

Conformance tests