# DM001 — Reconcilix Domain Model **Version:** 0.5 **Status:** Draft ED **Scope:** Source Provenance, Vocabulary and Entity Reconciliation **Related:** - `ADR001-*.md` - `ADR002_SOURCE_DELIVERY_MODEL_V4.md` - `IA001_ADR002_IMPACT_ON_DM_ME_DRAFT_ED.md` - `DM002_Persistence_Model_v0.3.md` - `ME001_Interpretation_Properties_and_Vocabulary_Matching_Patterns_v0.2_ALPHA.md` - `ME002_Interpretation_Driven_Reconciliation_v0.6_DRAFT.md` **Language Convention:** Fachbegriffe und Notationen in Englisch; erläuternder Fließtext in Deutsch. ## 1. Purpose DM001 beschreibt die fachlichen Objekte und Beziehungen, die Reconcilix für - die nachvollziehbare Herkunft und Gruppierung eingehender Daten, - die Interpretation eines `SourceValue`, - die Candidate Discovery, - die Reconciliation, - und die fachliche Match Decision verwendet. Das Modell ist unabhängig von einer konkreten Softwareimplementierung, API, Persistenztechnologie oder Matching Technique. Der fachliche Gesamtzusammenhang ist: ```text SourceSystem │ └── SourceDelivery ─── DeliveryChannel [0..1] │ └── SourceValue [1..*] │ └── InterpretationGraph [1..*] │ └── InterpretationNode [1..*] │ └── ReconciliationResult [0..*] ├── CandidateItem [0..*] └── MatchDecision [0..*] ``` Der eigentliche Interpretation-and-Reconciliation-Kern bleibt: ```text SourceValue → InterpretationGraph → InterpretationNode → ReconciliationResult → CandidateItem → MatchDecision ``` `SourceSystem`, `SourceDelivery` und `DeliveryChannel` bilden den fachlichen Herkunfts- und Lieferungskontext oberhalb dieses Kerns. Ein `SourceValue` wird nicht unmittelbar gegen `CandidateItem` gematcht. Zunächst werden eine oder mehrere interpretierbare Fundstellen verwaltet und mögliche Interpretationen rekursiv erschlossen. ## 2. Use Cases DM001 berücksichtigt vier Reconciliation Use Cases: 1. **Concept Reconciliation** — `preferredEntityType = CONCEPT` 2. **Person Reconciliation** — `preferredEntityType = PERSON` 3. **Place Reconciliation** — `preferredEntityType = PLACE` 4. **Text Reconciliation** — `preferredEntityType = MULTIPLE` Die nächste Implementierungsphase beschränkt sich bewusst auf: ```text OpenRefine → Reconcilix → xTree / MCT preferredEntityType = CONCEPT ``` Dabei gilt: ```text SourceSystem = fachliches Ursprungssystem SourceDelivery = konkrete Lieferung DeliveryChannel = technischer Übertragungsweg ``` Beispiel: ```text SourceSystem = digiCULT.web DeliveryChannel = OpenRefine Reconciliation API ``` OpenRefine wird in diesem Beispiel nicht als fachliches Ursprungssystem modelliert. Das Domain Model bleibt offen für weitere Clients, Quellsysteme, Delivery Channels und Target Vocabularies. ## 3. Provenance and Delivery Domain Classes ### 3.1 `SourceSystem` Das fachliche Ursprungssystem einer oder mehrerer Datenlieferungen. | Attribute | Meaning | |---|---| | `id` | Stabile interne Identität | | `name` | Fachlich lesbare Bezeichnung | | `uri` | Optionale stabile fachliche URI | Beispiele: - digiCULT.web - MuseumsPlus - Adlib Ein `SourceSystem` beschreibt weder - ein Dateiformat, - eine technische Schnittstelle, - einen Reconciliation Client, - noch einen Transportmechanismus. Ein `SourceSystem` ist ein eigenständiges Aggregate. ### 3.2 `SourceDelivery` Eine konkrete Lieferung aus genau einem `SourceSystem`. | Attribute | Meaning | |---|---| | `id` | Stabile interne Identität | | `sourceSystemId` | Referenz auf genau ein `SourceSystem` | | `deliveryChannel` | Optionaler technischer Übertragungsweg | | `externalDeliveryId` | Optionale Kennung aus dem Quell- oder Übertragungsprozess | | `receivedAt` | Zeitpunkt der Übernahme durch Reconcilix | Eine `SourceDelivery` - gehört genau zu einem `SourceSystem`, - kann optional genau einen `DeliveryChannel` referenzieren, - gruppiert fachlich `1..* SourceValue`, - übernimmt jedoch nicht den vollständigen Lebenszyklus der gruppierten `SourceValue`. `SourceDelivery` ist ein eigenständiges Aggregate. Das Gruppieren mehrerer `SourceValue` in einer `SourceDelivery` bedeutet nicht, dass die `SourceValue` Bestandteil desselben Aggregate sind. ### 3.3 `DeliveryChannel` Der technische Übertragungsweg, über den eine `SourceDelivery` Reconcilix erreicht. Beispiele: - `OPENREFINE_RECONCILIATION_API` - `CSV_IMPORT` - `REST_API` - `BATCH_IMPORT` Für v0.5 wird `DeliveryChannel` als kontrollierter fachlicher Wert beziehungsweise Value Object behandelt. `DeliveryChannel` ist: - kein `SourceSystem`, - kein eigenständiges Aggregate, - kein Schritt der Reconciliation Pipeline, - keine Matching Technique, - kein `ContextItem`. Die konkrete Persistenzform und die endgültige Vocabulary Strategy werden in DM002 beziehungsweise einer späteren Modellversion festgelegt. ## 4. Reconciliation Domain Classes ### 4.1 `SourceValue` Der unveränderte Eingangswert eines Reconciliation-Vorgangs. | Attribute | Meaning | |---|---| | `id` | Stabile interne Identität | | `sourceDeliveryId` | Referenz auf genau eine `SourceDelivery` | | `value` | Ursprünglicher Literalwert | | `sourceField` | Quellfeld oder Datenelement | | `sourceRecordId` | Referenz auf den Quelldatensatz | | `datatype` | Datentyp | | `language` | Sprache | | `preferredEntityType` | Erwarteter Entity Type | | `provenance` | Optionale ergänzende, wertbezogene Provenienz | | `createdAt` | Erstellungszeitpunkt | `sourceDeliveryId` ist verpflichtend. `provenance` darf ergänzende, wertbezogene Angaben enthalten, beispielsweise: - transformationsbezogene Hinweise, - quellwertspezifische technische Metadaten, - Informationen, die nicht bereits strukturiert über `SourceSystem`, `SourceDelivery` oder `DeliveryChannel` abgebildet werden. `provenance` ersetzt ausdrücklich nicht die strukturierte Zuordnung zu: - `SourceSystem`, - `SourceDelivery`, - `DeliveryChannel`. `preferredEntityType` wird nach unten vererbt. Es wird nicht redundant an `InterpretationGraph` oder `InterpretationNode` gespeichert. `SourceValue` bleibt ein eigenständiges Aggregate. ### 4.2 `ContextItem` Zusätzliche fachliche Information, die für Interpretation, Candidate Discovery oder Match Decision relevant sein kann. | Attribute | Meaning | |---|---| | `id` | Interne Identifikation | | `contextType` | Typ des Kontexts | | `value` | Kontextwert | | `source` | Optionale abweichende Herkunft | Für v0.5 gilt Kontext für den gesamten `SourceValue`. Eine Zuordnung zu einzelnen `InterpretationGraph`-Instanzen wird bewusst zurückgestellt. `SourceSystem`, `SourceDelivery` und `DeliveryChannel` sind keine `ContextItem`. Fachliche Informationen, die innerhalb einer Lieferung zusätzlich zu einem `SourceValue` bereitgestellt werden, können weiterhin als `ContextItem` modelliert werden. ### 4.3 `InterpretationGraph` Verwaltungs- und Arbeitseinheit für genau eine interpretierbare Fundstelle oder einen interpretierbaren Ausschnitt innerhalb eines `SourceValue`. | Attribute | Meaning | |---|---| | `id` | Interne Identifikation | | `spanStart` | Startposition im `SourceValue` | | `spanEnd` | Endposition im `SourceValue` | | `sourceFragment` | Unveränderter Ausschnitt | | `status` | Bearbeitungsstatus | | `version` | Version oder Lauf | | `createdAt` | Erstellungszeitpunkt | Ein `SourceValue` besitzt fachlich `1..* InterpretationGraph`. In der ersten Implementierung wird zunächst genau ein Graph unterstützt. Für einen nicht leeren interpretierbaren Ausschnitt gilt: ```text spanEnd > spanStart ``` `sourceFragment` muss beim Anlegen eines Graphen exakt aus dem unveränderten `SourceValue.value` anhand von `spanStart` und `spanEnd` gebildet werden. Beispiel: ```text SourceValue: "Der Herr von Bogen geht mit dem Bogen über den Bogen" InterpretationGraph[0] → erstes "Bogen" InterpretationGraph[1] → zweites "Bogen" InterpretationGraph[2] → drittes "Bogen" ``` ### 4.4 `InterpretationNode` Ein konkreter interpretierbarer Zustand innerhalb eines `InterpretationGraph`. | Attribute | Meaning | |---|---| | `id` | Interne Identifikation | | `value` | Interpretierter oder abgeleiteter Wert | | `level` | Ableitungstiefe | | `status` | Bearbeitungsstatus | | `createdBy` | Erzeugender Agent oder Systemteil | | `technique` | Optional verwendete Matching Technique | | `note` | Erläuterung | | `createdAt` | Erstellungszeitpunkt | Für `level` gilt: ```text Root Node: level = 0 Child Node: level = parent.level + 1 ``` Eine `InterpretationNode` repräsentiert keinen Bearbeitungsschritt, sondern einen fachlich interpretierbaren Zustand. Eine Node kann durch `0..* InterpretationProperty` klassifiziert werden. In v0.5 besitzt sie höchstens eine Parent Node. Echte konvergierende Graphpfade bleiben eine spätere Erweiterung. ### 4.5 `ReconciliationResult` Ergebnis eines konkreten Reconciliation-Versuchs für eine `InterpretationNode`. Ein `InterpretationNode` kann mehrere `ReconciliationResult` besitzen, beispielsweise für unterschiedliche Target Vocabularies oder Matching Strategies. | Attribute | Meaning | |---|---| | `id` | Interne Identifikation | | `success` | Vorläufiges Attribut ohne abschließend definierte fachliche Semantik | | `matchingStrategy` | Verwendete Matching Strategy | | `confidence` | Confidence des Ergebnisses | | `note` | Erläuterung | | `createdAt` | Erstellungszeitpunkt | | `targetVocabularyUri` | URI des Target Vocabulary | `success` wird in der ersten Implementierungsphase nicht für fachliche Entscheidungen, Evaluationen oder Workflow-Steuerung verwendet. Ein `ReconciliationResult` kann: - keinen Candidate enthalten, - einen oder mehrere Candidates enthalten, - mit `0..1 VocabularyMatchingPattern` klassifiziert werden, - eine oder mehrere `MatchDecision` erhalten. ### 4.6 `CandidateItem` Ein potenzielles Zielobjekt eines Reconciliation-Vorgangs. | Attribute | Meaning | |---|---| | `uri` | Fachliche persistente Identifikation | | `displayLabel` | Anzeigeform | | `entityType` | Tatsächlicher Entity Type | | `candidateSourceSystemUri` | URI des Systems oder Dienstes, aus dem der Candidate stammt | | `score` | Bewertung im Ergebnis | | `rank` | Rang in der Candidate List | | `qualifier` | Optionaler Qualifier beziehungsweise Homonymzusatz | `candidateSourceSystemUri` beschreibt die Herkunft des Candidates. Es ist semantisch strikt zu unterscheiden von: ```text SourceValue → SourceDelivery → SourceSystem ``` Diese Kette beschreibt die Herkunft des Eingangswerts. `SourceValue.preferredEntityType` ist die Erwartung; `CandidateItem.entityType` ist der tatsächlich festgestellte Typ. Für `rank` bleibt noch offen, ob - eine eindeutige Listenposition, - oder ein Rang mit zulässigen Gleichständen modelliert wird. ### 4.7 `MatchDecision` Fachliche oder automatische Entscheidung zu einem `ReconciliationResult`. | Attribute | Meaning | |---|---| | `id` | Interne Identifikation | | `decision` | Entscheidungstyp | | `confidence` | Confidence der Entscheidung | | `decidedBy` | Person, Rolle oder System | | `comment` | Erläuterung | | `timestamp` | Entscheidungszeitpunkt | | `decisionStatus` | Status der Entscheidung | | `selectedCandidateUri` | Optionale Referenz auf den ausgewählten Candidate | Eine `MatchDecision` kann optional auf ein ausgewähltes `CandidateItem` desselben `ReconciliationResult` verweisen. Ein `ReconciliationResult` kann mehrere `MatchDecision` erhalten. Entscheidungen werden nicht überschrieben. `decisionStatus` kennzeichnet den fachlichen Gültigkeitsstatus einer Entscheidung, beispielsweise: - vorläufig, - fachlich geprüft, - final. Die fachlich maßgebliche Entscheidung ist die als final klassifizierte Entscheidung. ## 5. Controlled Classifications ### 5.1 `InterpretationProperty` Kontrollierte Klassifikation einer `InterpretationNode`. Kardinalität: ```text InterpretationNode → 0..* InterpretationProperty ``` Beispiele: - `ORTHOGRAPHIC_VARIANT` - `COMPOSITE_TERM` - `MULTI_CONCEPT_EXPRESSION` ### 5.2 `VocabularyMatchingPattern` Kontrollierte Klassifikation eines `ReconciliationResult`. Kardinalität: ```text ReconciliationResult → 0..1 VocabularyMatchingPattern ``` Es beschreibt das dominante relationale Muster zwischen Interpretation und Candidate beziehungsweise das charakteristische Ergebnis eines erfolglosen Versuchs. Beispiele: - `EXACT_MATCH` - `LEXICAL_VARIANT` - `SEMANTIC_GENERALIZATION` - `CONTEXT_DEPENDENT` - `NO_SUITABLE_CONCEPT` ### 5.3 `DeliveryChannel` Kontrollierter Wert für den technischen Übertragungsweg einer `SourceDelivery`. Kardinalität: ```text SourceDelivery → 0..1 DeliveryChannel ``` Die konkrete URI-Struktur und Pflegeform werden in einer späteren Vocabulary- beziehungsweise Persistence-Entscheidung festgelegt. ## 6. Aggregate Boundaries DM001 v0.5 unterscheidet folgende Aggregate: ### 6.1 `SourceSystem` Aggregate Aggregate Root: ```text SourceSystem ``` Verantwortung: - stabile Identität des fachlichen Ursprungssystems, - fachlich lesbare Bezeichnung, - optionale URI. ### 6.2 `SourceDelivery` Aggregate Aggregate Root: ```text SourceDelivery ``` Verantwortung: - Zuordnung zu genau einem `SourceSystem`, - optionale Zuordnung eines `DeliveryChannel`, - Identifikation einer konkreten Lieferung, - Gruppierung der zugehörigen `SourceValue`. `SourceDelivery` speichert oder verändert `SourceValue` nicht automatisch als interne Aggregate-Bestandteile. ### 6.3 `SourceValue` Aggregate Aggregate Root: ```text SourceValue ``` Zum fachlichen Innenbereich gehören: ```text ContextItem InterpretationGraph InterpretationNode ReconciliationResult CandidateItem MatchDecision ``` Die genaue technische Persistenzgrenze kann aus Gründen der Skalierung und Repository-Struktur differenzierter umgesetzt werden. Fachlich bleiben diese Objekte jedoch auf einen `SourceValue` zurückführbar. ### 6.4 Cross-Aggregate References Zwischen den Aggregaten gelten ausschließlich stabile Referenzen: ```text SourceDelivery.sourceSystemId SourceValue.sourceDeliveryId ``` Ein Application Service kann mehrere Aggregate innerhalb einer Transaktion koordinieren. Dadurch werden die Aggregate-Grenzen nicht aufgehoben. ## 7. Domain Invariants ### 7.1 Provenance and Delivery 1. Jedes `SourceSystem` besitzt eine stabile Identität. 2. Jede `SourceDelivery` besitzt eine stabile Identität. 3. Jede `SourceDelivery` referenziert genau ein existierendes `SourceSystem`. 4. Jede `SourceDelivery` referenziert höchstens einen `DeliveryChannel`. 5. Jede `SourceDelivery` gruppiert fachlich mindestens einen `SourceValue`. 6. Jeder `SourceValue` referenziert genau eine existierende `SourceDelivery`. 7. Ein `DeliveryChannel` ist kein fachliches Ursprungssystem. 8. Ein Wechsel des technischen Übertragungswegs erzeugt nicht automatisch ein neues `SourceSystem`. 9. `SourceValue.provenance` darf die strukturierte Referenz auf `SourceDelivery` nicht ersetzen. 10. Eine `SourceDelivery` übernimmt nicht automatisch den Lebenszyklus ihrer `SourceValue`. Die Mindestkardinalität `SourceDelivery → SourceValue [1..*]` ist eine fachliche Invariante. Während eines technischen Erzeugungsprozesses kann eine `SourceDelivery` vorübergehend noch keinen persistenten `SourceValue` besitzen. Ein solcher Zwischenzustand darf die Transaktion beziehungsweise den Application Service nicht als fachlich vollständige Lieferung verlassen. ### 7.2 Interpretation and Reconciliation 1. Ein `SourceValue.value` ist nicht leer. 2. Ein `SourceValue.preferredEntityType` ist gesetzt. 3. Ein `InterpretationGraph` gehört genau zu einem `SourceValue`. 4. Für einen nicht leeren Graphen gilt `spanEnd > spanStart`. 5. `sourceFragment` entspricht exakt dem bezeichneten Ausschnitt von `SourceValue.value`. 6. Ein Root `InterpretationNode` besitzt `level = 0` und keine Parent Node. 7. Eine Child Node besitzt genau eine Parent Node und `level = parent.level + 1`. 8. Ein `CandidateItem.uri` ist innerhalb eines `ReconciliationResult` eindeutig. 9. Eine `MatchDecision` kann nur einen `CandidateItem` desselben `ReconciliationResult` auswählen. 10. Eine fachlich maßgebliche Entscheidung ist durch einen finalen `decisionStatus` gekennzeichnet. ## 8. UML Class Diagram ```mermaid classDiagram class SourceSystem { +id +name +uri } class SourceDelivery { +id +sourceSystemId +deliveryChannel +externalDeliveryId +receivedAt } class DeliveryChannel { +uri +code +label } class SourceValue { +id +sourceDeliveryId +value +sourceField +sourceRecordId +datatype +language +preferredEntityType +provenance +createdAt } class ContextItem { +id +contextType +value +source } class InterpretationGraph { +id +spanStart +spanEnd +sourceFragment +status +version +createdAt } class InterpretationNode { +id +value +level +status +createdBy +technique +note +createdAt } class InterpretationProperty { +uri +code +label +definition +status } class ReconciliationResult { +id +success +matchingStrategy +confidence +note +createdAt +targetVocabularyUri } class VocabularyMatchingPattern { +uri +code +label +definition +status } class CandidateItem { +uri +displayLabel +entityType +candidateSourceSystemUri +score +rank +qualifier } class MatchDecision { +id +decision +confidence +decidedBy +comment +timestamp +decisionStatus +selectedCandidateUri } SourceSystem "1" <-- "0..*" SourceDelivery : originatesFrom SourceDelivery "0..*" --> "0..1" DeliveryChannel : transferredVia SourceDelivery "1" <-- "1..*" SourceValue : belongsTo SourceValue "1" *-- "0..*" ContextItem : has SourceValue "1" *-- "1..*" InterpretationGraph : segmentedInto InterpretationGraph "1" *-- "1..*" InterpretationNode : contains InterpretationNode "0..1" --> "0..*" InterpretationNode : derives InterpretationNode "0..*" --> "0..*" InterpretationProperty : classifiedBy InterpretationNode "1" --> "0..*" ReconciliationResult : produces ReconciliationResult "0..*" --> "0..1" VocabularyMatchingPattern : classifiedBy ReconciliationResult "1" *-- "0..*" CandidateItem : contains ReconciliationResult "1" --> "0..*" MatchDecision : receives MatchDecision "0..*" --> "0..1" CandidateItem : selects ``` ## 9. Vocabulary Strategy Sobald die Klassifikationen fachlich stabil sind, werden dafür kleine kontrollierte Vokabulare in xTree angelegt und über den LOD-Dienst bereitgestellt. Die kontrollierten Vokabulare sind selbst Bestandteil der Reconcilix-Domäne und unabhängig von einem konkreten Target Vocabulary. Vorgesehen sind insbesondere: - `InterpretationProperty` - `VocabularyMatchingPattern` - `MatchDecision.decision` - `MatchDecision.decisionStatus` - `status` - `preferredEntityType` Für `DeliveryChannel` wird zunächst geprüft, ob - ein kleines kontrolliertes Reconcilix-Vokabular, - eine URI-basierte Konfiguration, - oder ein einfaches Value Object die angemessene Form darstellt. Auflösbare, kanonische URIs werden bevorzugt, beispielsweise: ```text https://reconcilix.vocnet.org/interpretation-property/ip0001 https://reconcilix.vocnet.org/vocabulary-matching-pattern/vmp0001 ``` ## 10. Implementation Boundary DM001 beschreibt das fachliche Zielmodell. Die erste Umsetzung von DM001 v0.5 soll sich beschränken auf: - `preferredEntityType = CONCEPT` - genau eine `SourceDelivery` je eingehender fachlicher Lieferung - verpflichtende Zuordnung jedes neuen `SourceValue` zu einer `SourceDelivery` - optionaler `DeliveryChannel` - zunächst genau einen `InterpretationGraph` pro `SourceValue` - MySQL als persistentes Backend - OpenRefine als Client und möglicher `DeliveryChannel` - xTree/MCT als Target Vocabulary - keine komplexe Graph Exploration - keine Qdrant-, BGE- oder LLM-Integration - keine automatische methodische Nutzung von `SourceSystem` oder `DeliveryChannel` Die Einführung von `SourceSystem` und `SourceDelivery` verändert den bestehenden Interpretation-and-Reconciliation-Kern nicht. ## 11. Deferred Design Questions Folgende Fragen werden bewusst nach der nächsten Modellierungs-, Implementierungs- oder Evaluationsrunde erneut geprüft: - Soll `SourceSystem.uri` verpflichtend werden? - Wird `DeliveryChannel` dauerhaft als Value Object behandelt oder später als kontrolliertes Vokabular ausgebaut? - Welche Metadaten gehören langfristig zu `SourceDelivery`? - Ist `externalDeliveryId` für alle Delivery Types sinnvoll? - Wie werden Wiederholungen, Versionen und Replays einer `SourceDelivery` modelliert? - Wie werden fachlich identische Lieferungen erkannt? - Kontext auf Graph- oder Node-Ebene - mehrere Parent Nodes und konvergierende Graphpfade - Versionierung und Replay vollständiger Reconciliation Runs - Spezialisierung von `CandidateItem` - mehrere `preferredEntityType` innerhalb eines `SourceValue` - endgültige Semantik von `ReconciliationResult.success` - Rangmodell bei `CandidateItem.rank` ## 12. Change Summary v0.4 → v0.5 DM001 v0.5 ergänzt gegenüber v0.4: 1. `SourceSystem` als fachliches Ursprungssystem. 2. `SourceDelivery` als konkrete Lieferung und Gruppierungsebene. 3. `DeliveryChannel` als optionalen technischen Übertragungsweg. 4. `SourceValue.sourceDeliveryId` als verpflichtende Referenz. 5. Präzisierung von `SourceValue.provenance`. 6. Explizite Aggregate-Grenzen. 7. Neue Provenienz- und Delivery-Invarianten. 8. Abgrenzung von Delivery Metadata und `ContextItem`. 9. Umbenennung von `CandidateItem.sourceSystem` zu `candidateSourceSystemUri`. 10. Erweiterung des UML-Diagramms.