4.2 Capability-Deklaration
4.2 Capability-Deklaration
Überblick
Das capabilities-Feld ist eine optionale Liste auf der Root-Ebene einer RUML-Datei. Es deklariert
alle Capabilities, die in dieser Datei verwendet werden, mit je einem Eintrag.
{ "$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" } } }}Positionierung im Root-Objekt
Das capabilities-Feld DARF im Root-Objekt einer RUML-Datei vorhanden sein.
Verhältnis zur Root-Struktur
Die vollständige Root-Objekt-Struktur ist in
Kapitel 2.2 definiert. Das capabilities-Feld
erweitert die optionalen Root-Felder um einen Eintrag.:::
Eintragsformat
Jeder Eintrag benennt seine Capability in id (nach der Namensraum-Konvention in
Kapitel 4.4) und trägt die folgenden Felder:
"capabilities": [ { "id": "ruml:ai-query", "required": true }, { "id": "com.example/custom-actions", "role": "reaction" }]| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id | String | MUSS | Die Capability-ID (siehe Kapitel 4.4). DARF NICHT mehr als einmal im Array vorkommen (siehe Eindeutigkeitsregel) (Regel CAP-09CAP-09 Jeder Eintrag der Root-capabilities MUSS id haben; ein Parser MUSS darin required und payload akzeptieren., Regel CAP-10CAP-10 Eine id DARF NICHT mehr als einmal in den Root-capabilities vorkommen.). |
required | Boolean | DARF | Wenn true: Parser MUSS diese Capability kennen, sonst MUSS er die Datei ablehnen. Wenn false oder abwesend: Ignorierung erlaubt. Standard: false; ruml:expression MUSS true deklarieren (Kapitel 4.14) (Regel CAP-11CAP-11 Der Root-Eintrag von ruml:expression MUSS required: true haben.) |
payload | Object | DARF | Alles Capability-Spezifische. Die Struktur wird durch die jeweilige Capability-Spezifikation definiert; die beiden konventionellen Unterfelder sind unten beschrieben (Regel CAP-09CAP-09 Jeder Eintrag der Root-capabilities MUSS id haben; ein Parser MUSS darin required und payload akzeptieren.). |
role | String | MUSS für nicht-offizielle IDs | Die Rolle, die die Rulemap von dieser Capability erwartet: data, decision, combiner oder reaction (siehe Kapitel 4.1, das auch die Regeln für ihre Deklaration festlegt) (Regel CAP-03CAP-03 Der Root-Eintrag einer ruml:draft/- oder Reverse-Domain-Capability MUSS role deklarieren.). |
Ein Capability-Eintrag ohne besondere Eigenschaften besteht nur aus id.
Konventionelle payload-Unterfelder:
| Unterfeld | Typ | Beschreibung |
|---|---|---|
payload.data | Object (Map) | Root-Level-Artefaktdaten als Map-Struktur (Key = ID). Wird von Capabilities verwendet, die benannte Objekte bereitstellen (z.B. DataPoints, Context, Texts). Siehe Abschnitt „Das data-Feld” unten. |
payload.config | Object | Globale Konfiguration dieser Capability. Wird von Capabilities verwendet, die Laufzeit-Parameter benötigen (z.B. systemPrompt bei ruml:ai-query). Siehe Abschnitt „Das config-Feld” unten. |
Das data-Feld
Das optionale data-Feld im payload eines Eintrags transportiert Root-Level-Artefaktdaten als
Map-Struktur (Key = ID, Value = Objekt). Es wird von Capabilities verwendet, die benannte Objekte
bereitstellen — z.B. DataPoint-Definitionen, Context-Materialien oder Rechtstexte.
Capabilities mit data-Feld:
ruml:datapoints— DataPoint-Definitionen (Key = DataPoint-ID)ruml:context— Context-Objekte (Key = Context-ID)ruml:text-reference— Rechtstexte (Key = Text-ID)
Regeln:
- Das
data-Feld MUSS eine Map-Struktur sein (Object mit benannten Keys) (Regel CAP-12CAP-12 Dasdataderpayloadeines Root-Eintrags MUSS ein Objekt mit IDs als Schlüsseln sein; ein Parser MUSS einepayloadmitdata,configoder beidem akzeptieren, soweit die Capability sie vorsieht.). - Ein Parser, der die Capability nicht implementiert und
required: falsevorfindet, MUSS dasdata-Feld ignorieren (Regel CAP-02CAP-02 Ein Parser MUSS eine Datei akzeptieren, die eine von ihm nicht implementierte Capability mitrequired: falseoder ohnerequireddeklariert, und MUSS diepayloadund die Einträge dieser Capability auf Node-Level ignorieren.). - Ein Parser, der die Capability kennt, MUSS das
data-Feld gemäß der Capability-Spezifikation validieren (Regel CAP-13CAP-13 Ein Parser, der eine Capability implementiert, MUSS derenpayload.dataundpayload.configgegen die Spezifikation dieser Capability validieren.).
"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" } } } } }]Das config-Feld
Das optionale config-Feld im payload eines Eintrags transportiert globale Konfiguration, die
für alle Ausführungen dieser Capability in der Datei gilt. Im Gegensatz zu data enthält es keine
benannten Artefakte, sondern Laufzeit-Parameter.
Regeln:
- Die Struktur von
configwird durch die jeweilige Capability-Spezifikation definiert. - Ein Parser, der die Capability nicht implementiert und
required: falsevorfindet, MUSS dasconfig-Feld ignorieren (Regel CAP-02CAP-02 Ein Parser MUSS eine Datei akzeptieren, die eine von ihm nicht implementierte Capability mitrequired: falseoder ohnerequireddeklariert, und MUSS diepayloadund die Einträge dieser Capability auf Node-Level ignorieren.). - Ein Parser, der die Capability kennt, MUSS das
config-Feld gemäß der Capability-Spezifikation validieren (Regel CAP-13CAP-13 Ein Parser, der eine Capability implementiert, MUSS derenpayload.dataundpayload.configgegen die Spezifikation dieser Capability validieren.). - Ein
payloadDARFdata,configoder beides enthalten — aber die Verwendung wird durch die Capability-Spezifikation festgelegt (Regel CAP-12CAP-12 Dasdataderpayloadeines Root-Eintrags MUSS ein Objekt mit IDs als Schlüsseln sein; ein Parser MUSS einepayloadmitdata,configoder beidem akzeptieren, soweit die Capability sie vorsieht.).
Parser-Verhalten bei required: true
Wenn eine Capability required: true hat und der Parser sie nicht implementiert (Regel CAP-01CAP-01 Ein Parser MUSS eine Datei ablehnen, die eine Capability mit required: true deklariert, die der Parser nicht implementiert, und DARF eine solche Datei NICHT teilweise verarbeiten.):
- Der Parser MUSS einen Fehler ausgeben, der die unbekannte Capability-ID nennt.
- Der Parser DARF die Datei NICHT partiell verarbeiten und dabei die unbekannten
capabilities-Daten stillschweigend verwerfen.
Fehler: Unbekannte erforderliche Capability 'com.example/custom-actions'. Diese Datei kann ohne Unterstützung dieser Capability nicht korrekt verarbeitet werden.Parser-Verhalten bei required: false
Wenn eine Capability required: false oder kein required hat und der Parser sie nicht
implementiert (Regel CAP-02CAP-02 Ein Parser MUSS eine Datei akzeptieren, die eine von ihm nicht implementierte Capability mit required: false oder ohne required deklariert, und MUSS die payload und die Einträge dieser Capability auf Node-Level ignorieren.):
- Der Parser DARF die Verarbeitung wegen dieser Capability NICHT abbrechen.
- Der Parser SOLLTE eine Warnung ausgeben, die die unbekannte Capability-ID nennt.
- Der Parser MUSS die entsprechenden
capabilities-Felder auf Knoten ignorieren.
Eine ruml:-ID, die diese Spezifikationsversion nicht definiert, fällt nicht unter Regel CAP-01CAP-01 Ein Parser MUSS eine Datei ablehnen, die eine Capability mit required: true deklariert, die der Parser nicht implementiert, und DARF eine solche Datei NICHT teilweise verarbeiten.
und Regel CAP-02CAP-02 Ein Parser MUSS eine Datei akzeptieren, die eine von ihm nicht implementierte Capability mit required: false oder ohne required deklariert, und MUSS die payload und die Einträge dieser Capability auf Node-Level ignorieren.: Ein Parser lehnt eine Datei, die sie enthält, unabhängig vom Wert von required
ab (Kapitel 4.4).
Eindeutigkeitsregel
Jede id DARF NICHT mehr als einmal im capabilities-Array vorkommen. Ein Parser MUSS eine
doppelte id als Validierungsfehler behandeln (Regel CAP-10CAP-10 Eine id DARF NICHT mehr als einmal in den Root-capabilities vorkommen.). Das Schema erzwingt dies nur für die
eingebauten ruml:-Capabilities; für ruml:draft/- und Drittanbieter-IDs ist die Prüfung eine
Parser-Pflicht, da das Schema Eindeutigkeit über einen offenen ID-Raum nicht erzwingen kann.
Die Regel gilt für das Array auf Root-Level. Ob ein Knoten dieselbe ID mehrfach führen darf, hängt von der Rolle der Capability ab (siehe Kapitel 4.3).
Abwesenheit des Feldes
Wenn capabilities im Root-Objekt fehlt oder ein leeres Array ist:
- Die Datei verwendet keine Capabilities.
- Das Feld
capabilitiesMUSS auf allen Knoten abwesend sein. Enthält ein Knoten dennoch eincapabilities-Feld, MUSS der Parser dies als Validierungsfehler behandeln (Regel CAP-14CAP-14 Ist das Root-capabilitiesnicht vorhanden oder leer, DARF ein Knoten NICHTcapabilitieshaben.).
Keine impliziten Capabilities
Ein Knoten DARF NICHT das capabilities-Feld befüllen, ohne die zugehörige Capability im
Root-Objekt deklariert zu haben — unabhängig davon, ob der Parser die Capability kennt oder nicht
(Regel CAP-15CAP-15 Die id jedes Eintrags der capabilities eines Knotens MUSS in den Root-capabilities deklariert sein.).:::
Vollständiges Beispiel
{ "$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" } } ] } } }}