Skip to content
RUMLRUML

Open Format for Digital Law

4.2 Capability Declaration

4.2 Capability Declaration

Overview

The capabilities field is an optional list at the root level of a RUML file. It declares all capabilities used in the file, one entry each.

{
"$format": "RUML",
"$specVersion": "1.0",
"capabilities": [],
"metadata": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"version": "1.0.0",
"created": "2024-01-01T00:00:00Z",
"modified": "2024-01-01T00:00:00Z",
"status": "inForce",
"validFrom": "2024-01-01T00:00:00Z"
},
"rulemap": {
"nodes": {
"1": {
"id": "0eb360a6-626a-406d-89a1-9f434ced141b",
"label": "Anspruch auf Schadensersatz"
}
}
}
}

Positioning in the Root Object

The capabilities field MAY be present in the root object of a RUML file.

Relationship to Root Structure

The complete root object structure is defined in Chapter 2.2. The capabilities field extends the optional root fields by one entry.:::

Entry Format

Each entry names its capability in id (following the namespace convention in Chapter 4.4) and carries the following fields:

"capabilities": [
{
"id": "ruml:ai-query",
"required": true
},
{
"id": "com.example/custom-actions",
"role": "reaction"
}
]
FieldTypeRequiredDescription
idStringMUSTThe capability ID (see Chapter 4.4). MUST NOT appear more than once in the array (see Uniqueness) (Rule CAP-09CAP-09 Every entry of the root capabilities MUST have id; a parser MUST accept required and payload in it., Rule CAP-10CAP-10 An id MUST NOT occur more than once in the root capabilities.).
requiredBooleanMAYIf true: parser MUST know this capability, otherwise it MUST reject the file. If false or absent: ignoring is permitted. Default: false; ruml:expression MUST declare true (Chapter 4.14) (Rule CAP-11CAP-11 The root entry of ruml:expression MUST have required: true.)
payloadObjectMAYEverything capability-specific. Its structure is defined by the respective capability specification; the two conventional sub-fields are described below (Rule CAP-09CAP-09 Every entry of the root capabilities MUST have id; a parser MUST accept required and payload in it.).
roleStringMUST for non-official idsThe role the rulemap expects this capability to play: data, decision, combiner or reaction (see Chapter 4.1, which also defines the rules for declaring it) (Rule CAP-03CAP-03 The root entry of a ruml:draft/ or reverse-domain capability MUST declare role.).

A capability entry with no special properties consists of id alone.

Conventional payload sub-fields:

Sub-fieldTypeDescription
payload.dataObject (Map)Root-level artifact data as a map structure (key = ID). Used by capabilities that provide named objects (e.g., DataPoints, Context, Texts). See section “The data field” below.
payload.configObjectGlobal configuration for this capability. Used by capabilities that require runtime parameters (e.g., systemPrompt for ruml:ai-query). See section “The config field” below.

The data Field

The optional data field inside an entry’s payload transports root-level artifact data as a map structure (key = ID, value = object). It is used by capabilities that provide named objects — e.g., DataPoint definitions, context materials, or legal texts.

Capabilities with data field:

  • ruml:datapoints — DataPoint definitions (key = DataPoint ID)
  • ruml:context — Context objects (key = context ID)
  • ruml:text-reference — Legal texts (key = text ID)

Rules:

  1. The data field MUST be a map structure (object with named keys) (Rule CAP-12CAP-12 The data of a root entry's payload MUST be an object keyed by id; a parser MUST accept a payload with data, config or both where the capability provides for them.).
  2. A parser that does not implement the capability and finds required: false MUST ignore the data field (Rule CAP-02CAP-02 A parser MUST accept a file that declares a capability it does not implement with required: false or without required, and MUST ignore the payload and the node-level entries of that capability.).
  3. A parser that knows the capability MUST validate the data field according to the capability specification (Rule CAP-13CAP-13 A parser that implements a capability MUST validate its payload.data and payload.config against that capability's specification.).
"capabilities": [
{
"id": "ruml:context",
"payload": {
"data": {
"ctx_guidance": {
"title": "Leitfaden zur Prüfung",
"category": "administrativeGuidance",
"type": "url",
"url": "https://example.com/leitfaden",
"timestamp": "2024-01-01T00:00:00Z"
}
}
}
},
{
"id": "ruml:datapoints",
"payload": {
"data": {
"dp_annual_income": {
"name": "Jahreseinkommen",
"type": "currency",
"unit": "EUR",
"binding": {
"type": "input"
}
}
}
}
}
]

The config Field

The optional config field inside an entry’s payload transports global configuration that applies to all executions of this capability within the file. Unlike data, it does not contain named artifacts but runtime parameters.

Rules:

  1. The structure of config is defined by the respective capability specification.
  2. A parser that does not implement the capability and finds required: false MUST ignore the config field (Rule CAP-02CAP-02 A parser MUST accept a file that declares a capability it does not implement with required: false or without required, and MUST ignore the payload and the node-level entries of that capability.).
  3. A parser that knows the capability MUST validate the config field according to the capability specification (Rule CAP-13CAP-13 A parser that implements a capability MUST validate its payload.data and payload.config against that capability's specification.).
  4. A payload MAY contain data, config, or both — but usage is determined by the capability specification (Rule CAP-12CAP-12 The data of a root entry's payload MUST be an object keyed by id; a parser MUST accept a payload with data, config or both where the capability provides for them.).

Parser Behavior for required: true

If a capability has required: true and the parser does not implement it (Rule CAP-01CAP-01 A parser MUST reject a file that declares a capability with required: true that the parser does not implement, and MUST NOT process such a file partially.):

  1. The parser MUST emit an error naming the unknown capability ID.
  2. The parser MUST NOT partially process the file while silently discarding the unknown capabilities data under any circumstances.
Error: Unknown required capability 'com.example/custom-actions'.
This file cannot be correctly processed without support for this capability.

Parser Behavior for required: false

If a capability has required: false or no required and the parser does not implement it (Rule CAP-02CAP-02 A parser MUST accept a file that declares a capability it does not implement with required: false or without required, and MUST ignore the payload and the node-level entries of that capability.):

  1. The parser MUST NOT abort processing because of this capability.
  2. The parser SHOULD emit a warning naming the unknown capability ID.
  3. The parser MUST ignore the corresponding capabilities fields on nodes.

A ruml: id that this specification version does not define is not covered by Rule CAP-01CAP-01 A parser MUST reject a file that declares a capability with required: true that the parser does not implement, and MUST NOT process such a file partially. and Rule CAP-02CAP-02 A parser MUST accept a file that declares a capability it does not implement with required: false or without required, and MUST ignore the payload and the node-level entries of that capability.: a parser rejects a file that contains it, whatever the value of required (Chapter 4.4).

Uniqueness

Each id MUST NOT appear more than once in the capabilities array. A parser MUST treat a duplicate id as a validation error (Rule CAP-10CAP-10 An id MUST NOT occur more than once in the root capabilities.). The schema enforces this only for the built-in ruml: capabilities; for ruml:draft/ and third-party ids the check is a parser obligation, because the schema cannot enforce uniqueness over an open id space.

The rule applies to the root-level array. Whether a node may carry the same id more than once depends on the capability’s role (see Chapter 4.3).

Absence of the Field

If capabilities is absent from the root object or is an empty array:

  • The file uses no capabilities.
  • The capabilities field MUST be absent on all nodes. If a node nevertheless contains a capabilities field, the parser MUST treat this as a validation error (Rule CAP-14CAP-14 When the root capabilities is absent or empty, a node MUST NOT have capabilities.).

No Implicit Capabilities

A node MUST NOT populate the capabilities field without the corresponding capability being declared in the root object — regardless of whether the parser knows the capability or not (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.).:::

Complete Example

{
"$format": "RUML",
"$specVersion": "1.0",
"capabilities": [
{
"id": "ruml:datapoints",
"payload": {
"data": {
"dp_damage": {
"name": "Schadenshöhe",
"type": "currency",
"unit": "EUR",
"binding": {
"type": "input"
}
},
"dp_causality": {
"name": "Kausalität gegeben",
"type": "boolean",
"binding": {
"type": "input"
}
}
}
}
},
{
"id": "ruml:query"
},
{
"id": "com.example/review-notes",
"required": true,
"role": "data"
}
],
"metadata": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"version": "1.0.0",
"created": "2024-06-01T00:00:00Z",
"modified": "2024-06-01T00:00:00Z",
"status": "inForce",
"validFrom": "2024-01-01T00:00:00Z"
},
"rulemap": {
"nodes": {
"1": {
"id": "0eb360a6-626a-406d-89a1-9f434ced141b",
"operator": "AND",
"label": "Anspruch auf Schadensersatz",
"children": ["2", "3"],
"capabilities": [
{
"id": "com.example/review-notes",
"payload": {
"status": "reviewed",
"reviewer": "rechtsabteilung"
}
}
]
},
"2": {
"id": "8fc54c7d-7f60-410e-9493-4f1eecfb1af8",
"label": "Schaden entstanden",
"capabilities": [
{
"id": "ruml:query",
"payload": {
"expression": "dp_damage > 0"
}
},
{
"id": "com.example/review-notes",
"payload": {
"status": "pending"
}
}
]
},
"3": {
"id": "56b5b9db-b791-4fe5-abb0-a05cb0847db6",
"label": "Kausalität gegeben",
"capabilities": [
{
"id": "ruml:query",
"payload": {
"expression": "dp_causality = true"
}
}
]
}
}
}
}

Conformance tests