diff --git a/docs/modules/ROOT/pages/ebenen.adoc b/docs/modules/ROOT/pages/ebenen.adoc index d13f536..4311956 100644 --- a/docs/modules/ROOT/pages/ebenen.adoc +++ b/docs/modules/ROOT/pages/ebenen.adoc @@ -1 +1,118 @@ -Folgende Ebenen sind vorgesehen: +Das Vokabular zur Beschreibung von Versicherungsservices muss modular aufgebaut sein und folgt einer Hierarchie von +der allgemeinen semantischen Bedeutung bis hin zur spezifischen lokalen Ausprägung. + +Dabei wird zwischen der **strukturellen Beschreibung** (Daten) und der **funktionalen Beschreibung** (API-Verhalten) unterschieden. + +Ziel ist, zwei Artefakte konsistent zu definieren: + +* Austauschobjekte (Datenobjekte): Welche Felder und Typen werden übertragen und validiert? +* Prozessvarianten (Abläufe): Welche Zustände existieren, welche Aktionen sind in welchem Zustand erlaubt? + ** Welche der normierten Prozessvarianten werden von der Versicherungsgesellschaft tatsächlich unterstützt + ** Welche zusätzlichen Services gibt es für ein spezielles Themengebiet (z.B. Versicherungsbestätigung für + Sparte Kfz) + ** Wie genau wurde ein Prozess von der Versicherungsgesellschaft implementiert: Bei der Antragsstrecke haben wir + derzeit eine stateles und eine stateful Variante. Es sollte für den Client erkennbar sein, welche Variante + implementiert wurde. + ** Welche zusätzlichen Services werden von der Versicherungsgesellschaft angeboten + +=== Schichtenmodell des Vokabulars + +Die Vokabulare bauen aufeinander auf ("Inheritance & Extension"), um Interoperabilität zu gewährleisten. + +[cols="1,1,2,2"] +|=== +|Kategorie |Bezeichnung | Zweck | Lieferobjekt + +.2+| **Technische Ebene** (API & Validierung) +| Hydra +| Definiert die *Dynamik* und *Businessprozesse*. Beschreibt Hypermedia-Controls, Operationen (z.B. `POST`, `PUT`) und wie Clients durch den Service navigieren können (State Transitions). +| Operation, Link, Collection, Erwartungen an Zustandswechsel + +| SHACL +| Definiert die *Validierungslogik*. Es beschränkt die offenen Vokabulare (FIBO, Schema.org) auf konkrete, validierbare Shapes ("Welche Felder sind Pflicht?", "Welche Wertebereiche sind erlaubt?"). +| Shape, Constraint, Severity + +| **Allgemeine Semantik** +| Schema.org +| Bietet das *gemeinsame Vokabular* (Upper Ontology) für Suchmaschinen (SEO) und KI-Agenten. Basisklassen wie `Person`, `Organization` oder `FinancialProduct` werden hier verankert. +| Klassen/Properties als generische Basistermine + +.2+| **Fachdomäne** (Core Domain) +| FIBO +| Die *Financial Industry Business Ontology* liefert die präzise, branchenübergreifende Definition von Finanzbegriffen (Vertragsrecht, Zinsen, wirtschaftliche Eigentümer), die Schema.org fehlen. +| Fachklassen/Properties, referenzierbare Definitionen + +| **Schema4i** +| (Optional) Spezifische Erweiterung für die *Versicherungswirtschaft*, basierend auf BiPro-Modellen, um Lücken zwischen FIBO (Finanzfokus) und Versicherungsprodukten zu schließen. +| Versicherungs-spezifische Klassen/Properties + +.4+| **Lokalisierung** (Specific Domain) +| OMDS Commons +| Marktübergreifende Begriffe, die spezifisch für den OMDS-Standard sind, aber noch keine nationale Besonderheit darstellen. +| Harmonisiertes Domänenvokabular + +| OMDS Austria +| Begriffe von lokaler österreichischer Bedeutung (z.B. Abbildung spezifischer Steuergesetze z.B. motorbezogene Kfz-Steuer, lokale Elemente wie "Bonus-Malus"). +| Lokale Erweiterungen/Constraints + +| OMDS Domänen & Sparten +| Festlegung von Begriffen und Regeln für einzelne Domänen und Sparten. +| Produkt-/Spartenprofile + +| VU-spezifische Ergänzungen +| VU-spezifische Ergänzungen für Domänen und Sparten. +| Lokale Profile/Regeln + + +|=== + +=== Unterscheidung: Geschäftsobjekte vs. Prozesse + +Für eine saubere Architektur ist die Trennung der Anliegen (Separation of Concerns) im Vokabular notwendig: + +1. **Geschäftsobjekte (Structural Vocabulary):** +Beschreiben das "WAS". +* Hierbei handelt es sich um RDF-Klassen und Properties (z.B. definiert durch Schema.org/FIBO). +* Beispiel: Eine Instanz einer `InsurancePolicy` mit Attributen wie `startDate`, `premium`. +* Diese Definitionen sind meist zustandslos und wiederverwendbar. + +2. **Businessprozesse (Behavioural Vocabulary / Hydra):** +Beschreiben das "WIE". +* Hier wird definiert, welche *Aktionen* auf den Geschäftsobjekten ausgeführt werden dürfen. +* Hydra `Operation`: Definiert den API-Aufruf (z.B. `SubmitClaim`). +* Status-Modelle: Definition von Prozesszuständen (z.B. `ClaimProcessingStage`), die oft im OMDS-Layer definiert werden müssen, da sie sehr spezifisch für die Abwicklungslogik sind. + +=== Prozessvarianten modellieren (Hydra + Zustandsmodell) + +Um Varianten sauber zu kommunizieren, wird ein Prozess als Zustandsmaschine beschrieben. Wichtig ist: Die **zulässigen Operationen sind objekt- und kontextabhängig zur Laufzeit**. Ein Objekt signalisiert also seinen aktuellen Handlungsspielraum durch die angebotenen Hydra-Operationen (Hypermedia als State of the Resource). + +* **State**: benannter Zustand eines Geschäftsobjekts (z.B. `ClaimDraft`, `ClaimSubmitted`). +* **Transition**: definierter Wechsel zwischen Zuständen, ausgelöst durch eine Operation. +* **Preconditions**: fachliche Bedingungen, die vor Ausführung erfüllt sein müssen. +* **Result-Objekt**: welches Objekt bzw. welcher Status nach der Operation resultiert. + +Hydra definiert dabei die Operationen und Links, SHACL validiert die Datenobjekte, die als Input/Output der Operationen verwendet werden. + +=== Austauschobjekte & Profile (SHACL) + +Ein **Profil** definiert ein austauschbares Datenobjekt als Kombination aus: + +* **Subset** der Klassen/Properties aus Schema.org/FIBO/OMDS. +* **Constraints** (Pflichtfelder, Kardinalität, Wertebereiche). +* **Businessregeln** (z.B. bedingte Pflichtfelder) als SHACL-Constraints. + +So lassen sich Datenobjekte eindeutig und testbar zwischen Partnern definieren. + +=== Minimales Beispiel (Skizze) + +```json +{ + "@context": "https://schema.org", + "@type": "InsuranceProduct", + "name": "Haushalt Premium", + "category": "PropertyInsurance" +} +``` + +* **Hydra Operation**: `RequestOffer` auf `InsuranceProduct` erlaubt nur im Zustand `ProductActive`. +* **SHACL Shape**: `InsuranceProductShape` fordert `name` und `category` als Pflichtfelder.