Skip to content
RUMLRUML

Open Format for Digital Law

4.13 ruml:protocol

4.13 Capability ruml:protocol

Overview

PropertyValue
Capability IDruml:protocol
ScopeRoot-Level (declaration only)
Default requiredfalse
Rolereaction

This Capability requests an evaluation protocol: a chronological, machine-readable record of everything the engine did during an evaluation — written into the RUML-Result file (see Chapter 5). It provides full traceability for audit purposes, including events that never appear in a node result: data resolution, warnings, aborts, short-circuit skips.

The protocol complements the per-node results: node results hold the detailed outcome per node (status, capability details), the protocol holds the sequence of the run.

Root-Level Declaration

"capabilities": [
{
"id": "ruml:protocol",
"required": true,
"payload": {
"config": {
"level": "standard"
}
}
}
]

There is no data object and no node-level payload — the capability is a directive to the evaluating engine. ruml:protocol MUST NOT appear in a node’s capabilities array, neither inline nor in a RUML-EXT file (Rule CAP-18CAP-18 ruml:protocol MUST NOT appear in a node's capabilities, neither inline nor in a RUML-EXT file.).

Semantics:

  • If ruml:protocol is declared, the engine SHOULD write a protocol into the result.
  • If declared with required: true, the engine MUST write a protocol. An engine that cannot produce one MUST NOT evaluate the file.
  • Engines MAY write a protocol even when the capability is not declared.

Configuration (config):

FieldTypeDescription
levelEnumMAY specify the verbosity: standard (default) or verbose. See the event vocabulary below (Rule CAP-36CAP-36 A parser MUST accept config.level with the value standard or verbose in the root payload of ruml:protocol.).

Protocol Format: CloudEvents

The protocol is stored in the RUML-Result file inside the evaluation.capabilities entry with id: "ruml:protocol" — consistent with how all capability-produced data appears in results:

FieldTypeDescription
levelEnumThe verbosity level the protocol was recorded at (standard or verbose)
eventsArrayThe protocol: a JSON array conforming to the CloudEvents v1.0 JSON Batch Format (standalone media type: application/cloudevents-batch+json)

Each entry in events is a CloudEvent; RUML defines the following profile on top of CloudEvents v1.0:

AttributeCloudEventsRUML profile
specversionrequiredMUST be "1.0"
idrequiredMUST be unique within the protocol (CloudEvents: source + id unique)
sourcerequired (URI-reference)MUST identify the evaluating engine (and SHOULD include its version); an absolute URI is RECOMMENDED
typerequiredMUST be one of the ruml.* event types below, or a custom type that does NOT use the ruml. prefix
timeoptional in CloudEventsREQUIRED in this profile (RFC 3339)
subjectoptionalThe node path or datapoint ID the event refers to, where applicable
dataoptionalEvent payload as a direct JSON value (no datacontenttype ⇒ treated as application/json per CloudEvents)

Ordering: CloudEvents does not define event ordering. In this profile, the array order is normative: events MUST appear in the order the engine produced them. time alone is not sufficient (multiple events may share a timestamp).

Note on type naming: CloudEvents recommends reverse-DNS type prefixes; this profile deliberately uses the short ruml. prefix for specification-defined events. Implementation-specific events MUST use a distinct prefix of their own.

Event Vocabulary

TypeLevelsubjectdata
ruml.evaluation.startedstandard—{ "mode": … }
ruml.evaluation.completedstandard—MAY contain summary values
ruml.evaluation.abortedstandard—{ "reason": … }
ruml.node.evaluatedstandardnode path{ "lexId": …, "status": …, "capability"?: …, "reason"?: … }
ruml.node.skippedverbosenode path{ "lexId": …, "cause": "shortCircuit" }
ruml.datapoint.resolvedverbosedatapoint ID{ "binding": …, "value"?: … }
ruml.action.triggeredstandardnode path{ "operation": …, "trigger": …, "status": … }
ruml.warningstandardoptional{ "message": …, "code"?: … }
ruml.errorstandardoptional{ "message": …, "code"?: … }

standard events MUST be written at both levels; verbose events MUST NOT be written at level: "standard". Implementations MAY define additional event types (own prefix).

Sensitive data: the values of datapoints declared sensitive: true (see Chapter 4.7) MUST NOT appear in the protocol — neither in data.value nor in messages.

Example

{
"$format": "RUML-Result",
"$specVersion": "1.0",
"rumlReference": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934"
},
"evaluation": {
"id": "d8129e0c-cf2e-4ef9-b7b6-fa8b206d5517",
"timestamp": "2024-01-15T10:00:05Z",
"mode": "complete",
"results": {
"1": {
"lexId": "1",
"status": "true",
"reason": "Child 1.1 is true"
},
"1.1": {
"lexId": "2",
"status": "true",
"reason": "ruml:query yields true for dp_annual_income 50000"
}
},
"capabilities": [
{
"id": "ruml:protocol",
"payload": {
"level": "verbose",
"events": [
{
"specversion": "1.0",
"id": "0001",
"source": "https://engines.example.com/rms-engine/2.3.1",
"type": "ruml.evaluation.started",
"time": "2024-01-15T10:00:00Z",
"data": {
"mode": "complete"
}
},
{
"specversion": "1.0",
"id": "0002",
"source": "https://engines.example.com/rms-engine/2.3.1",
"type": "ruml.datapoint.resolved",
"time": "2024-01-15T10:00:01Z",
"subject": "dp_annual_income",
"data": {
"binding": "input",
"value": 50000
}
},
{
"specversion": "1.0",
"id": "0003",
"source": "https://engines.example.com/rms-engine/2.3.1",
"type": "ruml.node.evaluated",
"time": "2024-01-15T10:00:02Z",
"subject": "1.1",
"data": {
"lexId": "2",
"status": "true",
"capability": "ruml:query"
}
},
{
"specversion": "1.0",
"id": "0004",
"source": "https://engines.example.com/rms-engine/2.3.1",
"type": "ruml.node.evaluated",
"time": "2024-01-15T10:00:03Z",
"subject": "1",
"data": {
"lexId": "1",
"status": "true"
}
},
{
"specversion": "1.0",
"id": "0005",
"source": "https://engines.example.com/rms-engine/2.3.1",
"type": "ruml.evaluation.completed",
"time": "2024-01-15T10:00:05Z"
}
]
}
}
]
}
}

Engine Obligations

IDRequirement
PT-01If ruml:protocol is declared with required: true, the engine MUST write the protocol into payload.events of the evaluation.capabilities entry with id: "ruml:protocol"; an engine that cannot MUST NOT evaluate the file
PT-02Every protocol entry MUST conform to CloudEvents v1.0 (JSON format); the array order MUST be the order of occurrence
PT-03time MUST be present on every event (RFC 3339)
PT-04Values of sensitive datapoints MUST NOT appear in the protocol
PT-05Implementation-specific event types MUST NOT use the ruml. prefix