Zum Inhalt springen
RUMLRUML

Open Format for Digital Law

4.5 RUML-EXT-Format

4.5 RUML-EXT-Format

Überblick

Das RUML-EXT-Format definiert eine Sidecar-Datei, die Capability-Erweiterungsdaten separat von der Ursprungs-RUML-Datei speichert. Sie ergänzt die in Kapitel 4.1 beschriebene Inline-Methode durch den Sidecar-Modus.

  • Dateiendung: .ruml-ext
  • Format-Identifikation: $format: "RUML-EXT"
  • Zweck: Transport von capabilities-Daten ohne Modifikation der Ursprungs-RUML-Datei
  • Schema: ruml-ext.schema.json (Draft 2020-12)

Root-Objekt-Struktur

Eine RUML-EXT-Datei MUSS folgende Pflichtfelder enthalten:

{
"$format": "RUML-EXT",
"$specVersion": "1.0",
"$base": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"hash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
},
"capabilities": [/* ... */],
"nodes": {/* ... */}
}
FeldTypPflichtBeschreibung
$formatStringMUSSMUSS den Wert "RUML-EXT" haben
$specVersionStringMUSSDieselben Versionierungsregeln wie RUML (siehe Kapitel 2.3)
$baseObjectMUSSReferenz auf die Basis-RUML-Datei (siehe unten)
capabilitiesArrayMUSSDie Capabilities, deren Daten in dieser EXT-Datei enthalten sind — eine Liste von Einträgen wie in Kapitel 4.2, deren Reihenfolge nicht signifikant ist
nodesObjectMUSSErweiterungsdaten, indexiert über UUIDs

Ein Parser MUSS prüfen, ob $format den Wert "RUML-EXT" hat, bevor er die EXT-Datei weiterverarbeitet (Regel CAP-22CAP-22 $format einer RUML-EXT-Datei MUSS "RUML-EXT" sein; ein Parser MUSS das prüfen, bevor er die Datei weiter verarbeitet.).

Das Root-Objekt einer RUML-EXT-Datei DARF NICHT die Felder metadata und rulemap enthalten — sie sind ausschließlich der Basis-RUML-Datei vorbehalten (Regel CAP-23CAP-23 Der Root einer RUML-EXT-Datei DARF NICHT metadata oder rulemap enthalten.). Ein Parser MUSS das Vorhandensein eines dieser Felder als Validierungsfehler behandeln. evaluation ist ebenfalls kein EXT-Root-Feld — es gehört in RUML-Result-Dateien (.ruml-result) —, ist aber nicht Teil der Regel CAP-23CAP-23 Der Root einer RUML-EXT-Datei DARF NICHT metadata oder rulemap enthalten.-Prüfung.

Root-Level-Artefaktdaten werden NICHT als eigene Root-Felder der EXT-Datei transportiert, sondern über das payload.data-Feld des jeweiligen Eintrags im capabilities-Array (siehe Kapitel 4.2).

Das $base-Feld

"$base": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"hash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
}
FeldTypPflichtBeschreibung
idUUIDMUSSDie metadata.id der Basis-RUML-Datei. MUSS dem UUID-v4-Format entsprechen (Pattern ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$).
hashStringMUSSDer Hash der Basis-RUML-Datei zum Zeitpunkt der Erstellung dieser EXT-Datei.

Der Hash MUSS über die kanonische Form der Basis-RUML-Datei nach den Hashing-Regeln des Containers berechnet werden (Kapitel 2.4, Kapitel 7.3). Er identifiziert die exakte Version der Basis-Datei, auf die sich die EXT-Datei bezieht.

Hash-Verifizierung

Bevor ein Parser die Erweiterungsdaten aus einer RUML-EXT-Datei mit einer RUML-Datei zusammenführt, MUSS er folgende Schritte durchführen (Regel CAP-24CAP-24 Vor einem Merge MUSS $base.id einer RUML-EXT-Datei gleich metadata.id der Basis-RUML-Datei sein und ihr $base.hash gleich dem Hash der kanonischen Form der Basis-RUML-Datei; andernfalls MUSS der Parser den Merge abbrechen. Jede RUML-EXT-Datei wird für sich geprüft.):

  1. ID-Abgleich: Die $base.id der EXT-Datei MUSS mit der metadata.id der RUML-Datei übereinstimmen.
  2. Hash-Verifizierung: Der aktuelle Hash der RUML-Datei MUSS mit dem $base.hash der EXT-Datei übereinstimmen.
  3. Wenn der Hash nicht übereinstimmt: Der Parser MUSS den Merge abbrechen und einen Fehler ausgeben.

Ein Parser DARF NICHT auf diesen Hash-Abgleich verzichten — auch nicht in Entwicklungsumgebungen oder bei explizitem Benutzer-Override, sofern die Spezifikation keine Ausnahme definiert (Regel CAP-25CAP-25 Ein Parser DARF den $base-Vergleich NICHT überspringen, auch nicht in einer Entwicklungsumgebung oder bei explizitem Benutzer-Override.).

Veraltete EXT-Datei

Wenn die Basis-RUML-Datei seit der Erstellung der EXT-Datei verändert wurde, stimmt der Hash nicht mehr überein. Der Parser MUSS in diesem Fall den Merge ablehnen. Ein stilles Zusammenführen veralteter Erweiterungsdaten würde zu inkonsistenten Zuständen führen.

Das nodes-Objekt in RUML-EXT

Die Erweiterungsdaten im nodes-Objekt sind über UUIDs (nicht LexIDs) indexiert. Dies ist notwendig, weil LexIDs bei modularen Knoten nicht eindeutig positions-adressierbar sind, UUIDs hingegen global eindeutig.

"nodes": {
"0eb360a6-626a-406d-89a1-9f434ced141b": {
"com.example/review-notes": {
"status": "approved",
"reviewer": "rechtsabteilung"
}
// ...
},
"8fc54c7d-7f60-410e-9493-4f1eecfb1af8": {
"com.example/review-notes": {
"status": "pending"
}
}
// ...
}
  • Schlüssel: Eine gültige UUID, die im nodes-Objekt der Basis-RUML-Datei existiert (der Wert des id-Felds des Knotens).
  • Wert: Ein Objekt, dessen Schlüssel Capability-IDs aus dem capabilities-Array der EXT-Datei sind.

Unbekannte UUID-Referenzen

Wenn eine UUID im nodes-Objekt der EXT-Datei keinem Knoten in der Basis-RUML-Datei entspricht, MUSS der Parser dies als Fehler behandeln (Regel CAP-26CAP-26 Jede Knoten-UUID in den nodes einer RUML-EXT-Datei MUSS die id eines Knotens der Basis-RUML-Datei sein.). Dies verhindert stille Daten-Phantome (Erweiterungsdaten für nicht-existente Knoten).

Vollständiges Beispiel

Basis-RUML-Datei (pruefung-volljährigkeit.ruml):

{
"$format": "RUML",
"$specVersion": "1.0",
"capabilities": [
{
"id": "ruml:query"
},
{
"id": "ruml:datapoints",
"payload": {
"data": {
"dp_age": {
"name": "Alter",
"type": "integer",
"binding": {
"type": "input"
}
},
"dp_competent": {
"name": "Geschäftsfähig",
"type": "boolean",
"binding": {
"type": "input"
}
}
}
}
}
],
"metadata": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"version": "1.2.0",
"created": "2024-01-15T09:00:00Z",
"modified": "2024-03-20T14:30:00Z",
"status": "inForce",
"validFrom": "2024-01-01T00:00:00Z"
},
"rulemap": {
"nodes": {
"1": {
"id": "0eb360a6-626a-406d-89a1-9f434ced141b",
"operator": "AND",
"label": "Geschäftsfähigkeit",
"children": ["2", "3"]
},
"2": {
"id": "8fc54c7d-7f60-410e-9493-4f1eecfb1af8",
"label": "Volljährigkeit",
"capabilities": [
{
"id": "ruml:query",
"payload": {
"expression": "dp_age >= 18"
}
}
]
},
"3": {
"id": "56b5b9db-b791-4fe5-abb0-a05cb0847db6",
"label": "Keine Entmündigung",
"capabilities": [
{
"id": "ruml:query",
"payload": {
"expression": "dp_competent = true"
}
}
]
}
}
}
}

RUML-EXT-Sidecar (pruefung-volljährigkeit.ruml-ext):

{
"$format": "RUML-EXT",
"$specVersion": "1.0",
"$base": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"hash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
},
"capabilities": [
{
"id": "com.example/review-notes",
"role": "data"
},
{
"id": "com.example/priority",
"role": "data"
}
],
"nodes": {
"0eb360a6-626a-406d-89a1-9f434ced141b": {
"com.example/review-notes": {
"status": "approved",
"reviewer": "rechtsabteilung"
},
"com.example/priority": {
"level": "high"
}
},
"8fc54c7d-7f60-410e-9493-4f1eecfb1af8": {
"com.example/review-notes": {
"status": "pending"
}
},
"56b5b9db-b791-4fe5-abb0-a05cb0847db6": {
"com.example/review-notes": {
"status": "approved",
"reviewer": "rechtsabteilung"
},
"com.example/priority": {
"level": "low"
}
}
}
}

Verhältnis zur Inline-Methode

Es ist nicht erlaubt, dieselbe Capability für denselben Knoten gleichzeitig inline (im capabilities-Feld) und in einer EXT-Datei zu definieren. Bei einem Merge MUSS der Parser prüfen, ob ein Konflikt vorliegt, und diesen als Fehler behandeln (Regel CAP-27CAP-27 Dieselbe Capability DARF für denselben Knoten NICHT zugleich inline und in einer RUML-EXT-Datei definiert sein, auch nicht in zwei RUML-EXT-Dateien derselben Basis-RUML-Datei; ein Parser MUSS mehrere RUML-EXT-Dateien für eine Basis-RUML-Datei akzeptieren.). Eine stille Überschreibung oder Zusammenführung DARF NICHT erfolgen.

Mehrere EXT-Dateien für eine RUML-Datei

Es DARF mehrere EXT-Dateien geben, die dieselbe Basis-RUML-Datei referenzieren — z.B. eine EXT-Datei pro Capability-Anbieter. Jede EXT-Datei MUSS unabhängig verifiziert werden. Konflikte zwischen EXT-Dateien (gleiche Capability auf gleichem Knoten in zwei verschiedenen EXT-Dateien) MÜSSEN als Fehler behandelt werden (Regel CAP-27CAP-27 Dieselbe Capability DARF für denselben Knoten NICHT zugleich inline und in einer RUML-EXT-Datei definiert sein, auch nicht in zwei RUML-EXT-Dateien derselben Basis-RUML-Datei; ein Parser MUSS mehrere RUML-EXT-Dateien für eine Basis-RUML-Datei akzeptieren.).