4.8 ruml:query
4.8 Capability ruml:query
Overview
| Property | Value |
|---|---|
| Capability ID | ruml:query |
| Scope | Node-Level (capabilities entry with id: "ruml:query") |
Default required | false |
| Role | decision |
This Capability defines data-based queries on Leaf-Nodes that determine their truth value. Queries
access DataPoints defined via the ruml:datapoints Capability (see
Chapter 4.7).
Distinction from other Capabilities
For normative text references, ruml:text-reference is used (see
Chapter 4.12). ruml:query covers exclusively data-based queries.
For AI-assisted decisions, the separate Capability ruml:ai-query is used (see
Chapter 4.9).
Root-Level Declaration
To use ruml:query, the Capability MUST be declared in the root capabilities array
(Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.):
"capabilities": [ { "id": "ruml:query" }]Note: DataPoints are defined via the standalone ruml:datapoints Capability (see
Chapter 4.7). ruml:query accesses the data points defined there but does not
itself contain a data object.
Node-Level Query
On Leaf-Nodes, the query is provided in the capabilities array of the node:
"1": { "id": "0eb360a6-626a-406d-89a1-9f434ced141b", "label": "Einkommen ausreichend", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_annual_income > 50000" } } ]}Node-Level Query Fields
| Field | Type | Description |
|---|---|---|
expression | String | MUST contain a JSONata expression for computing the truth value (Rule CAP-29CAP-29 A node's ruml:query payload MUST have expression, a valid JSONata expression; a parser MUST accept description in it.) |
description | String | MAY contain a description of the query (Rule CAP-29CAP-29 A node's ruml:query payload MUST have expression, a valid JSONata expression; a parser MUST accept description in it.) |
Expression Format
Expressions MUST be written in JSONata 2.2.0.
The expression is evaluated against an input document: a JSON object that holds the value of each DataPoint under the DataPoint’s id. A DataPoint without a value has no entry.
A result of true or false is the status of the node. Any other result — including no result —
MUST yield status undefined.
"expression": "dp_annual_income > 50000"Evaluation Rules
- A node with a
ruml:queryentry incapabilitiesMUST NOT have a non-emptychildrenarray - A node with a non-empty
childrenarray MUST NOT have aruml:queryentry incapabilities(Rule CAP-07CAP-07 An entry of a capability with thedecisionrole MUST NOT appear on a node withchildren.) ruml:querydetermines the truth value of a Leaf-Node; Actions (theruml:actionsentry) react to the truth value — both are independent concepts- All DataPoint IDs referenced in the expression MUST be defined in the
ruml:datapointsCapability (referential integrity,Rule DP-18DP-18 Every DataPoint id that theexpressionof aruml:queryor of aruml:expressionreads, and every id ininputs.dataPointsof aruml:ai-query, MUST be a key of thedataofruml:datapoints.)
Combination with Other Capabilities
A node can combine ruml:query with other Capabilities:
"1": { "id": "fcf02185-ffee-48a4-bf93-d2fb1b17944d", "label": "Einkommensprüfung", "capabilities": [ { "id": "ruml:text-reference", "payload": { "refs": [ { "id": "text_sgb_ii_11", "type": "refers-to" } ] } }, { "id": "ruml:query", "payload": { "expression": "dp_annual_income > 50000" } }, { "id": "ruml:actions", "payload": { "onTrue": { "operation": "createDocument", "ref": "approval_service" }, "onFalse": { "operation": "sendNotification", "ref": "rejection_service" } } } ]}Complete Example
{ "$format": "RUML", "$specVersion": "1.0", "capabilities": [ { "id": "ruml:datapoints", "payload": { "data": { "dp_annual_income": { "name": "Jahreseinkommen", "type": "currency", "unit": "EUR", "binding": { "type": "input" }, "validation": { "required": true, "min": 0 } }, "dp_credit_score": { "name": "Bonitätsscore", "type": "number", "binding": { "type": "external", "ref": "schufa_api" } } } } }, { "id": "ruml:query" }, { "id": "ruml:text-reference", "payload": { "data": { "text_bgb_488": { "title": "§ 488 BGB – Darlehensvertrag", "uri": "/akn/de/act/1896-08-18/bgb#sec_488", "timestamp": "2024-01-01T00:00:00Z", "status": "inForce", "type": "embedded", "text": "Durch den Darlehensvertrag wird der Darlehensgeber verpflichtet, dem Darlehensnehmer einen Geldbetrag in der vereinbarten Höhe zur Verfügung zu stellen. Der Darlehensnehmer ist verpflichtet, einen geschuldeten Zins zu zahlen und bei Fälligkeit das zur Verfügung gestellte Darlehen zurückzuzahlen." } } } } ], "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": "ec36948d-fbb2-4815-985a-bd5e9375d934", "operator": "AND", "label": "Kreditprüfung", "capabilities": [ { "id": "ruml:text-reference", "payload": { "refs": [ { "id": "text_bgb_488", "type": "refers-to" } ] } } ], "children": ["2", "3"] }, "2": { "id": "0eb360a6-626a-406d-89a1-9f434ced141b", "label": "Einkommen ausreichend", "capabilities": [ { "id": "ruml:query", "payload": { "description": "Mindesteinkommensgrenze", "expression": "dp_annual_income > 50000" } } ] }, "3": { "id": "6840b48d-117f-474e-ae4e-337b8e60537c", "label": "Bonität ausreichend", "capabilities": [ { "id": "ruml:query", "payload": { "expression": "dp_credit_score >= 600" } } ] } } }}Delivery via RUML-EXT (Sidecar)
When ruml:query is delivered via a RUML-EXT file, the node-level queries are provided in the
nodes object (keyed by UUID):
{ "$format": "RUML-EXT", "$specVersion": "1.0", "$base": { "id": "7812e8d0-bd75-437e-9c20-e4f8fb028ced", "hash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2" }, "capabilities": [ { "id": "ruml:query" } ], "nodes": { "0eb360a6-626a-406d-89a1-9f434ced141b": { "ruml:query": { "expression": "dp_annual_income > 50000" } } }}