Skip to content
RUMLRUML

Open Format for Digital Law

4.4 Namespaces for Capability IDs

4.4 Namespaces for Capability IDs

Purpose

Capability IDs MUST be globally unique to prevent collisions between capabilities from different providers. A namespace mechanism based on prefixes ensures this uniqueness.

Each capability ID consists of a prefix and a local name, separated by a defined delimiter.

Prefix Table

PrefixDelimiterOwnerNormativityDescription
ruml::RUML Specification BodyNormativeOfficial capabilities of the RUML specification — reserved
ruml:draft/: + /RUML Specification BodyExperimentalExperimental capabilities; MAY change without notice
<reverse-domain>/. + /Third partyVendor-specificArbitrary third parties following the reverse-domain convention

A parser MUST verify that every capability ID conforms to one of these prefixes. It MUST treat an ID without a recognizable prefix pattern as an error (Rule CAP-21CAP-21 A capability id MUST be a ruml: id defined by this specification version, a ruml:draft/<name> id or a <reverse-domain>/<name> id; it MUST consist of lowercase letters, digits, _, - and the delimiters, and MUST NOT exceed 128 characters.).

Namespace Reservation

The prefix ruml: is reserved. Third parties MUST NOT use this prefix for their own capabilities. A parser MUST reject a file that contains a ruml: id that is neither defined by this specification version nor a ruml:draft/ id, whatever the value of required.

Official Capabilities (ruml:)

Capabilities under the ruml: prefix (without draft/) are part of the RUML specification. They MUST be documented in an official capability registry and follow the versioning rules of the specification (see Chapter 2.3).

Official Capability Registry

The following ruml: capabilities are defined in the current specification:

Capability IDScopeDescriptionSpecification
ruml:datapointsRoot (data)DataPoints schema (data definitions) and binding hintsChapter 4.7
ruml:queryNodeData-based query expression (leaf nodes)Chapter 4.8
ruml:ai-queryNodeAI-powered decisions (LLM-based)Chapter 4.9
ruml:actionsNodeAction objects on any node (reactions to status)Chapter 4.10
ruml:contextRoot (data) + NodeContext map (context materials) and node referencesChapter 4.11
ruml:text-referenceRoot (data) + NodeTexts map (legal texts/norms) and node referencesChapter 4.12
ruml:protocolRoot (declaration)Evaluation protocol (audit trail) written into the result fileChapter 4.13
ruml:expressionRoot (declaration) + NodeCombination expression for the DELEGATED operator (parent nodes)Chapter 4.14
ruml:tree-referenceRoot (declaration) + NodeReferences to nodes, and their subtrees, of other RUML filesChapter 4.15
ruml:tree-includeRoot (declaration) + NodeEvaluates a node of another RUML file in place of a leaf nodeChapter 4.16

Experimental Capabilities (ruml:draft/)

Capabilities under the ruml:draft/ prefix are in draft status:

  • MAY change in name, structure, or semantics without notice.
  • SHOULD NOT be used with required: true in production files.
  • MAY be promoted to official ruml: capabilities or discarded in future versions.

Upgrade Path

When a ruml:draft/ capability becomes stable, it receives a new ID without draft/. Files using the draft capability must be migrated manually.

Third-Party Capabilities (Reverse Domain)

All capabilities outside the ruml: namespace follow the reverse-domain convention:

com.example/review-notes
io.acme.legaltools/citation-style
org.myproject/custom-operator

The format is: <reverse-domain>/<local-name>

  • The reverse-domain part MUST reflect a valid domain hierarchy owned by the provider.
  • The local name MUST be at least one character long.
  • The root-level entry MUST declare the role the rulemap expects the capability to play (see Chapter 4.1; Rule CAP-03CAP-03 The root entry of a ruml:draft/ or reverse-domain capability MUST declare role.). A parser that implements the capability rejects the file if the declared role differs from its implementation (Rule CAP-04CAP-04 A parser that implements a ruml:draft/ or reverse-domain capability MUST reject the file if the declared role differs from the role it implements.).

Syntax Rules

RuleDescription
Character setAllowed: [a-z0-9_-], plus the delimiters from the prefix table and / (as hierarchy separator)
Minimum lengthAt least 1 character
Maximum lengthMUST NOT exceed 128 characters
CaseLower case only; upper-case letters are NOT allowed
WhitespaceNOT allowed

Valid and Invalid Examples

// VALID
"ruml:query"
"ruml:draft/ai-annotations"
"com.example/review-notes"
"com.example/priority"
"io.acme/v2/legal-refs"
"de.justiz.nrw/aktenzeichen"
// INVALID — whitespace
"com.example/my capability"
// INVALID — upper case
"com.example/Review-Notes"
// INVALID — reserved prefix for third parties
"ruml:my-vendor-extension"
// INVALID — no domain, no delimiter
"layout"
"myextension"
// INVALID — empty local name
"com.example/"