# DM001 — Reconcilix Domain Model

**Version:** 0.4  
**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, API oder Matching Technique.

Der fachliche Kern ist:

```text
SourceValue
→ InterpretationGraph
→ InterpretationNode
→ ReconciliationResult
→ CandidateItem
→ MatchDecision
```

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 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
```

Das Domain Model bleibt dennoch offen für die übrigen Use Cases.

## 3. Core Domain Classes

### 3.1 `SourceValue`

Der unveränderte Eingangswert eines Reconciliation-Vorgangs.

| Attribute | Meaning |
|---|---|
| `id` | Interne eindeutige Identifikation |
| `value` | Ursprünglicher Literalwert |
| `sourceField` | Quellfeld oder Datenelement |
| `sourceRecordId` | Referenz auf den Quelldatensatz |
| `datatype` | Datentyp |
| `language` | Sprache |
| `preferredEntityType` | Erwarteter Entity Type |
| `provenance` | Herkunft des ursprünglichen Werts |

`preferredEntityType` wird nach unten vererbt. Es wird nicht redundant an `InterpretationGraph` oder `InterpretationNode` gespeichert.

### 3.2 `ContextItem`

Zusätzliche 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.4 gilt Kontext für den gesamten `SourceValue`. Eine Zuordnung zu einzelnen `InterpretationGraph`-Instanzen wird bewusst zurückgestellt.

### 3.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.

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"
```

### 3.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 |

Eine Node kann durch `0..* InterpretationProperty` klassifiziert werden. In v0.4 besitzt sie höchstens eine Parent Node; echte konvergierende Graphpfade bleiben eine spätere Erweiterung.

### 3.5 `ReconciliationResult`

Ergebnis eines konkreten Reconciliation-Versuchs für eine `InterpretationNode`.

| Attribute | Meaning |
|---|---|
| `id` | Interne Identifikation |
| `success` | Erfolg des Versuchs |
| `matchingStrategy` | Verwendete Matching Strategy |
| `confidence` | Confidence des Ergebnisses |
| `note` | Erläuterung |
| `createdAt` | Erstellungszeitpunkt |
| `targetVocabularyUri` | URI des Target Vocabulary oder Source System |

Ein `ReconciliationResult` kann:

- keinen Candidate enthalten,
- einen oder mehrere Candidates enthalten,
- mit `0..1 VocabularyMatchingPattern` klassifiziert werden,
- eine oder mehrere `MatchDecision` erhalten.

### 3.6 `CandidateItem`

Ein potenzielles Zielobjekt eines Reconciliation-Vorgangs.

| Attribute | Meaning |
|---|---|
| `uri` | Fachliche persistente Identifikation |
| `displayLabel` | Anzeigeform |
| `entityType` | Tatsächlicher Entity Type |
| `sourceSystem` | Zielsystem oder Datenquelle |
| `score` | Bewertung im Ergebnis |
| `rank` | Rang in der Candidate List |
| `qualifier` | Optionaler Qualifier bzw. Homonymzusatz |

`SourceValue.preferredEntityType` ist die Erwartung; `CandidateItem.entityType` ist der tatsächlich festgestellte Typ.

### 3.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 |

Eine `MatchDecision` kann optional auf ein ausgewähltes `CandidateItem` verweisen.

## 4. Controlled Classifications

### 4.1 `InterpretationProperty`

Kontrollierte Klassifikation einer `InterpretationNode`.

Kardinalität:

```text
InterpretationNode → 0..* InterpretationProperty
```

Beispiele:

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

### 4.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. UML Class Diagram

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

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

    class InterpretationGraph {
        +id
        +spanStart
        +spanEnd
        +sourceFragment
        +status
        +version
        +createdAt
    }

    class InterpretationNode {
        +id
        +value
        +level
        +status
        +createdBy
        +technique
        +note
    }

    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
        +sourceSystem
        +score
        +rank
        +qualifier
    }

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

    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
```

## 6. Vocabulary Strategy

Sobald die Klassifikationen fachlich stabil sind, werden dafür kleine kontrollierte Vokabulare in xTree angelegt und über den LOD-Dienst bereitgestellt.

Vorgesehen sind insbesondere:

- `InterpretationProperty`
- `VocabularyMatchingPattern`
- `MatchDecision.decision`
- `status`
- `preferredEntityType`

Auflösbare, sprechende URIs werden bevorzugt, beispielsweise:

```text
https://reconcilix.vocnet.org/interpretation-property/composite-term
https://reconcilix.vocnet.org/vocabulary-matching-pattern/semantic-generalization
```

## 7. Implementation Boundary

DM001 beschreibt das fachliche Zielmodell. Die erste Umsetzung beschränkt sich auf:

- `preferredEntityType = CONCEPT`
- zunächst genau einen `InterpretationGraph` pro `SourceValue`
- MySQL als persistentes Backend
- OpenRefine als Client
- xTree/MCT als Target Vocabulary
- keine komplexe Graph Exploration
- keine Qdrant-, BGE- oder LLM-Integration

## 8. Deferred Design Questions

Folgende Fragen werden bewusst nach der ersten Implementierungs- und Evaluationsrunde erneut geprüft:

- Kontext auf Graph- oder Node-Ebene
- mehrere Parent Nodes und konvergierende Graphpfade
- Versionierung und Replay vollständiger Runs
- Spezialisierung von `CandidateItem`
- mehrere `preferredEntityType` innerhalb eines `SourceValue`