# DM001 — Reconcilix Domain Model

**Version:** 0.1  
**Status:** Draft  
**Scope:** Vocabulary and Entity Reconciliation  
**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 Interpretation und Reconciliation eines `SourceValue` verwendet. Das Modell ist unabhängig von einer konkreten Softwareimplementierung, einem bestimmten `Concept Scheme` oder einer bestimmten Reconciliation-Technik.

Der Ausgangspunkt ist nicht mehr ausschließlich

```text
SourceValue → CandidateItem
```

sondern
[public](../../public)
```text
SourceValue
→ InterpretationGraph
→ InterpretationNode
→ ReconciliationResult
→ CandidateItem
→ MatchDecision
```

Der `InterpretationGraph` ermöglicht rekursive, parallele und kontextabhängige Interpretationen eines `SourceValue`, bevor oder während Candidate Items entdeckt und bewertet werden.

## 2. Scope

DM001 berücksichtigt zunächst vier Use Cases:

1. **Concept Reconciliation**  
   `SourceValue` enthält einen Sachbegriff; erwarteter `preferredEntityType` ist `CONCEPT`.

2. **Person Reconciliation**  
   `SourceValue` enthält eine Personenbezeichnung; erwarteter `preferredEntityType` ist `PERSON`.

3. **Place Reconciliation**  
   `SourceValue` enthält eine Adresse oder Ortsbezeichnung; erwarteter `preferredEntityType` ist `PLACE`.

4. **Text Reconciliation**  
   `SourceValue` enthält fortlaufenden Text mit mehreren interpretierbaren Einheiten; `preferredEntityType` ist `MULTIPLE` oder nicht abschließend vorgegeben.

Nicht Gegenstand von DM001 sind konkrete Implementierungen, APIs, Datenbanken, Matching-Modelle oder technische Produkte wie OpenRefine, Qdrant, BGE oder LLMs.

## 3. Core Domain Classes

### 3.1 `SourceValue`

Ein `SourceValue` ist der unveränderte Eingangswert eines Reconciliation-Vorgangs. Er bleibt während der gesamten Verarbeitung erhalten und dient als Referenz für alle daraus abgeleiteten Interpretationen.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `value` | Ursprünglicher Literalwert |
| `sourceField` | Herkunftsfeld oder Datenelement |
| `sourceRecordId` | Referenz auf den Quelldatensatz |
| `datatype` | Datentyp des Werts |
| `language` | Sprache des Werts |
| `preferredEntityType` | Erwarteter Entity Type, z. B. `CONCEPT`, `PERSON`, `PLACE`, `MULTIPLE` |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

Ein `SourceValue` kann über `ContextItem` um zusätzliche Informationen ergänzt werden.

### 3.2 `ContextItem`

Ein `ContextItem` stellt zusätzliche Information bereit, die für Interpretation, Candidate Discovery oder Match Decision relevant sein kann.

**Examples**

- TEI-Ausschnitt
- Lebensdaten
- Note
- Ort oder übergeordnetes Geografikum
- GeoNames URI
- Geokoordinate
- Feld- oder Objektkontext

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `contextType` | Typ des Kontexts |
| `value` | Kontextwert |
| `source` | Herkunft des Kontexts |
| `relationToSourceValue` | Beziehung zum `SourceValue` |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

### 3.3 `InterpretationGraph`

Der `InterpretationGraph` ist die fachliche Arbeits- und Verwaltungseinheit für die Exploration möglicher Interpretationen eines `SourceValue`.

Er verwaltet:

- alle `InterpretationNode` eines Reconciliation-Vorgangs,
- einen oder mehrere Root Nodes,
- rekursive Ableitungen,
- parallele Interpretationspfade,
- Segmentierung und Spans innerhalb längerer Texte,
- alternative oder konkurrierende Interpretationen,
- den Status der gesamten Exploration,
- Graph-weite Provenance.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `sourceValueId` | Referenz auf den `SourceValue` |
| `status` | Bearbeitungsstatus des Graphen |
| `version` | Version oder Ausführung des Graphen |
| `createdAt` | Erstellungszeitpunkt |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

Der Begriff `Graph` wird bewusst verwendet. Ein rein hierarchischer Baum wäre zu eng, weil unterschiedliche Interpretationspfade zu derselben Interpretation konvergieren können und Nodes mehrere Vorgänger oder Nachfolger besitzen können.

### 3.4 `InterpretationNode`

Eine `InterpretationNode` repräsentiert einen konkreten interpretierbaren Zustand oder Ausschnitt innerhalb des `InterpretationGraph`.

Eine Node kann:

- den vollständigen `SourceValue` repräsentieren,
- einen normalisierten Wert enthalten,
- einen Textspan oder Token repräsentieren,
- aus einer oder mehreren anderen Nodes abgeleitet sein,
- weitere Nodes erzeugen,
- durch eine oder mehrere `InterpretationProperty` klassifiziert werden,
- mehrere `ReconciliationResult` produzieren.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `value` | Interpretierter oder abgeleiteter Wert |
| `spanStart` | Startposition im `SourceValue` |
| `spanEnd` | Endposition im `SourceValue` |
| `level` | Ableitungstiefe im Graphen |
| `status` | Status der Node |
| `method` | Verfahren, durch das die Node entstand |
| `note` | Erläuterung |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

### 3.5 `ReconciliationResult`

Ein `ReconciliationResult` dokumentiert das Ergebnis eines konkreten Reconciliation-Versuchs für eine `InterpretationNode`.

Es ist eine eigenständige Klasse, weil:

- ein Versuch ohne Candidate enden kann,
- ein Versuch mehrere Candidates enthalten kann,
- dieselbe Node mit mehreren `MatchingStrategy`-Varianten bearbeitet werden kann,
- Erfolg, Confidence und `VocabularyMatchingPattern` für den konkreten Versuch gelten,
- ein Ergebnis neue Interpretationen oder weitere Exploration auslösen kann.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `success` | Gibt an, ob ein ausreichend positives Ergebnis erzielt wurde |
| `matchingStrategy` | Verwendete Matching Strategy |
| `vocabularyMatchingPattern` | Klassifikation der Beziehung zum Candidate oder des Ergebnisses |
| `confidence` | Confidence des Ergebnisses |
| `note` | Erläuterung |
| `createdAt` | Erstellungszeitpunkt |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

### 3.6 `CandidateItem`

Ein `CandidateItem` ist ein potenzielles Zielobjekt eines Reconciliation-Vorgangs.

Die neutrale Benennung ersetzt `CandidateConcept`, weil Reconcilix neben Concepts auch Personen, Orte und weitere Entity Types reconciliieren soll.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Lokale Identifikation |
| `uri` | Persistente Identifikation im Zielsystem |
| `displayLabel` | Anzeigeform |
| `entityType` | `CONCEPT`, `PERSON`, `PLACE` oder anderer Entity Type |
| `sourceSystem` | Zielsystem oder Datenquelle |
| `score` | Bewertung innerhalb eines `ReconciliationResult` |
| `rank` | Rang innerhalb der Candidate List |
| `qualifier` | Optionaler Qualifier bzw. Homonymzusatz |
| `provenance` | Herkunfts- und Verarbeitungsinformationen |

Typspezifische Informationen, etwa `preferredTerm`, `alternativeTerm`, `conceptScheme`, Lebensdaten oder Geokoordinaten, können später über Spezialisierungen oder zusätzliche Properties modelliert werden. Für v0.1 bleibt `CandidateItem` bewusst generisch.

### 3.7 `MatchDecision`

Eine `MatchDecision` dokumentiert eine fachliche oder automatische Entscheidung zu einem `ReconciliationResult`.

**Possible decisions**

- `ACCEPTED`
- `REJECTED`
- `NEEDS_CONTEXT`
- `MANUAL_REVIEW`
- `NO_SUITABLE_CANDIDATE`

Eine `MatchDecision` kann optional auf ein ausgewähltes `CandidateItem` verweisen. Damit sind auch Entscheidungen ohne Candidate möglich.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `decision` | Entscheidungstyp |
| `confidence` | Confidence der Entscheidung |
| `decidedBy` | Person, Rolle oder System |
| `comment` | Erläuterung |
| `timestamp` | Entscheidungszeitpunkt |

## 4. Classifications

### 4.1 `InterpretationProperty`

`InterpretationProperty` ist keine Kernklasse des Domain Model, sondern eine kontrollierte Klassifikation einer `InterpretationNode`.

Sie beschreibt intrinsische Eigenschaften einer Interpretation, beispielsweise:

- `ORTHOGRAPHIC_VARIANT`
- `COMPOSITE_TERM`
- `MULTI_CONCEPT_EXPRESSION`

Eine Node kann mehrere `InterpretationProperty` gleichzeitig besitzen.

### 4.2 `VocabularyMatchingPattern`

`VocabularyMatchingPattern` ist ebenfalls eine kontrollierte Klassifikation. Es beschreibt die Beziehung zwischen einer `InterpretationNode`, einem `ReconciliationResult` und gegebenenfalls einem `CandidateItem`.

Examples:

- `EXACT_MATCH`
- `LEXICAL_VARIANT`
- `SEMANTIC_GENERALIZATION`
- `CONTEXT_DEPENDENT`
- `WRONG_SEMANTIC_CLASS`
- `NO_SUITABLE_CONCEPT`

Ein `VocabularyMatchingPattern` wird auf Ebene des `ReconciliationResult` dokumentiert, da es vom konkreten Reconciliation-Versuch und dessen Candidate Items abhängt.

## 5. UML Class Diagram

```mermaid
classDiagram
    class SourceValue {
        +id
        +value
        +sourceField
        +sourceRecordId
        +datatype
        +language
        +preferredEntityType
        +provenance
    }

    class ContextItem {
        +id
        +contextType
        +value
        +source
        +relationToSourceValue
        +provenance
    }

    class InterpretationGraph {
        +id
        +sourceValueId
        +status
        +version
        +createdAt
        +provenance
    }

    class InterpretationNode {
        +id
        +value
        +spanStart
        +spanEnd
        +level
        +status
        +method
        +note
        +provenance
    }

    class InterpretationProperty {
        <<classification>>
        +propertyType
        +confidence
        +note
    }

    class ReconciliationResult {
        +id
        +success
        +matchingStrategy
        +vocabularyMatchingPattern
        +confidence
        +note
        +createdAt
        +provenance
    }

    class CandidateItem {
        +id
        +uri
        +displayLabel
        +entityType
        +sourceSystem
        +score
        +rank
        +qualifier
        +provenance
    }

    class VocabularyMatchingPattern {
        <<classification>>
        +patternType
        +confidence
        +note
    }

    class MatchDecision {
        +id
        +decision
        +confidence
        +decidedBy
        +comment
        +timestamp
    }

    SourceValue "1" --> "0..*" ContextItem : has
    SourceValue "1" --> "1" InterpretationGraph : initiates

    InterpretationGraph "1" *-- "1..*" InterpretationNode : contains
    InterpretationNode "0..*" --> "0..*" InterpretationNode : derivesFrom
    InterpretationNode "1" --> "0..*" InterpretationProperty : classifiedBy

    InterpretationNode "1" --> "0..*" ReconciliationResult : produces
    ReconciliationResult "1" *-- "0..*" CandidateItem : contains
    ReconciliationResult "1" --> "0..1" VocabularyMatchingPattern : classifiedBy

    ReconciliationResult "1" --> "0..*" MatchDecision : receives
    MatchDecision "0..*" --> "0..1" CandidateItem : selects
```

## 6. InterpretationGraph Examples

### 6.1 Orthographic normalization

```text
SourceValue: "Altrarretabel"

InterpretationGraph
└── InterpretationNode 0: "Altrarretabel"
    └── InterpretationNode 1: "Altarretabel"
```

Possible classifications:

```text
InterpretationNode 0
InterpretationProperty = ORTHOGRAPHIC_VARIANT
```

Ein `ReconciliationResult` für Node 1 kann anschließend Candidate Items enthalten und beispielsweise als `EXACT_MATCH` oder `SEMANTIC_GENERALIZATION` klassifiziert werden.

### 6.2 Composite term and semantic generalization

```text
SourceValue: "Abendmahlsrelief"

InterpretationGraph
└── InterpretationNode 0: "Abendmahlsrelief"
    └── InterpretationNode 1: "Relief"
```

```text
InterpretationNode 0
InterpretationProperty = COMPOSITE_TERM

ReconciliationResult for InterpretationNode 1
CandidateItem = Relief
VocabularyMatchingPattern = SEMANTIC_GENERALIZATION
```

### 6.3 Multiple expressions in continuous text

```text
SourceValue:
"Der Herr von Bogen geht mit dem Bogen über den Bogen"
```

Der `InterpretationGraph` kann mehrere Root- oder Span Nodes verwalten:

```text
InterpretationNode A
value = "Bogen"
span = first occurrence

InterpretationNode B
value = "Bogen"
span = second occurrence

InterpretationNode C
value = "Bogen"
span = third occurrence
```

Der übergeordnete oder initiale Node kann durch `MULTI_CONCEPT_EXPRESSION` klassifiziert werden. Jede Span Node kann anschließend unabhängig interpretiert und reconciliiert werden, gegebenenfalls unter Nutzung von Kontext.

## 7. Use Case Mapping

| Use Case | `preferredEntityType` | Typical graph structure | Candidate type |
|---|---|---|---|
| Sachbegriff | `CONCEPT` | Meist ein Root Node mit rekursiven Ableitungen | `CONCEPT` |
| Person | `PERSON` | Ein oder mehrere Name Interpretations unter Einbezug von Lebensdaten und Notes | `PERSON` |
| Ort | `PLACE` | Nodes für Adresse, Ortsname und geografische Bestandteile | `PLACE` |
| Text | `MULTIPLE` | Mehrere Root- oder Span Nodes mit eigenen Ableitungen | Mixed |

## 8. Open Questions for v0.2

1. Kann ein `SourceValue` mehrere `InterpretationGraph` besitzen, etwa für unterschiedliche Runs oder Strategien, oder wird dies ausschließlich über `version` abgebildet?
2. Soll `ContextItem` ausschließlich dem `SourceValue` oder zusätzlich einzelnen `InterpretationNode` zugeordnet werden können?
3. Benötigt `ReconciliationResult` eine explizite Referenz auf das verwendete Target Vocabulary oder Source System?
4. Soll `VocabularyMatchingPattern` genau einmal oder mehrfach pro `ReconciliationResult` vergeben werden können?
5. Wie werden mehrere akzeptierte Candidate Items bei `preferredEntityType = MULTIPLE` in `MatchDecision` abgebildet?
6. Wann ist eine Interpretation abgeschlossen und wann wird eine weitere `MatchingStrategy` ausgelöst?
7. Welche Attribute gehören in DM001 und welche erst in ein späteres Logical oder Technical Model?

## 9. Relationship to Other Documents

- **ME001** definiert die kontrollierten Klassifikationen `InterpretationProperty` und `VocabularyMatchingPattern`.
- **ME002** beschreibt den iterativen Prozess, in dem ein `InterpretationGraph` erweitert, Candidate Items entdeckt und Match Decisions getroffen werden.
- **ROADMAP_MATCHING** dokumentiert die Capabilities und Techniques, die für diese Verarbeitung umgesetzt werden sollen.

DM001 ist diesen Dokumenten fachlich vorgelagert, ohne eine lineare Entwicklungsreihenfolge vorzugeben. Die Dokumente werden iterativ gegeneinander validiert.