# DM001 — Reconcilix Domain Model

**Version:** 0.3  
**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

```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 des ursprünglichen Werts |

Ein `SourceValue` kann über `ContextItem` um zusätzliche Informationen ergänzt werden. Für v0.3 gilt ein `ContextItem` jeweils für den gesamten `SourceValue`; eine Zuordnung zu einzelnen Fundstellen oder Nodes wird bewusst nicht modelliert.

Ein `SourceValue` besitzt mindestens einen `InterpretationGraph`. Bei längeren Texten oder `MULTI_CONCEPT_EXPRESSION` kann er in mehrere interpretierbare Spans und damit mehrere `InterpretationGraph` segmentiert 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` | Optionale abweichende Herkunft des Kontexts, z. B. GeoNames oder eine externe Note |

Die Provenance des `SourceValue` wird nach unten vererbt. Eine eigene `source` wird nur benötigt, wenn der Kontext aus einer abweichenden Quelle stammt.

### 3.3 `InterpretationGraph`

Der `InterpretationGraph` ist die fachliche Arbeits- und Verwaltungseinheit für **genau eine interpretierbare Fundstelle oder einen interpretierbaren Ausschnitt** innerhalb eines `SourceValue`.

Er verwaltet:

- den referenzierten Span im unveränderten `SourceValue`,
- das daraus gebildete `sourceFragment`,
- alle `InterpretationNode` dieser Fundstelle,
- einen oder mehrere Root Nodes,
- rekursive Ableitungen,
- parallele Interpretationspfade,
- alternative oder konkurrierende Interpretationen,
- den Status und die Version der Exploration für diese Fundstelle.

Ein `SourceValue` kann mehrere `InterpretationGraph` besitzen. Das ist insbesondere bei `MULTI_CONCEPT_EXPRESSION` und bei fortlaufendem Text relevant. Für

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

entstehen beispielsweise drei `InterpretationGraph`, je einer für jede interpretierbare Fundstelle von „Bogen“.

**Suggested attributes**

| Attribute | Meaning |
|---|---|
| `id` | Eindeutige Identifikation |
| `sourceValueId` | Referenz auf den `SourceValue` |
| `spanStart` | Startposition der Fundstelle im `SourceValue` |
| `spanEnd` | Endposition der Fundstelle im `SourceValue` |
| `sourceFragment` | Unveränderter Ausschnitt aus dem `SourceValue` |
| `status` | Bearbeitungsstatus des Graphen |
| `version` | Version oder Ausführung des Graphen |
| `createdAt` | Erstellungszeitpunkt |

`preferredEntityType` wird vom `SourceValue` als Constraint nach unten vererbt und deshalb nicht redundant am `InterpretationGraph` modelliert.

Der Begriff `Graph` wird bewusst verwendet. Für v0.3 besitzt eine `InterpretationNode` zwar höchstens eine Parent Node; das Modell bleibt aber offen für spätere konvergierende Pfade und echte Many-to-many-Ableitungen.

### 3.4 `InterpretationNode`

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

Eine Node kann:

- das im Graphen verwaltete `sourceFragment` repräsentieren,
- einen normalisierten oder semantisch abgeleiteten Wert enthalten,
- aus höchstens einer anderen Node 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 |
| `level` | Ableitungstiefe im Graphen |
| `status` | Status der Node |
| `createdBy` | Agent, Rolle oder System, das die Node erzeugt hat |
| `technique` | Optionales Verfahren, durch das die Node entstand |
| `note` | Erläuterung |

Die Herkunft des ursprünglichen Werts wird über den `SourceValue` vererbt. `createdBy` und `technique` dokumentieren stattdessen die Derivation der Node.

### 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 |
| `confidence` | Confidence des Ergebnisses |
| `note` | Erläuterung |
| `createdAt` | Erstellungszeitpunkt |
| `targetVocabularyUri` | URI des verwendeten Target Vocabulary oder Source System |

Ein `ReconciliationResult` kann mit höchstens einem dominanten `VocabularyMatchingPattern` klassifiziert werden (`0..1`).

### 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 |
|---|---|
| `uri` | Persistente Identifikation im Zielsystem; primäre fachliche Identifikation |
| `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 |

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

`SourceValue.preferredEntityType` bezeichnet den erwarteten Typ; `CandidateItem.entityType` den tatsächlich festgestellten Typ.

### 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. Controlled 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 (`0..*`).

### 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. Pro `ReconciliationResult` wird höchstens ein dominantes `VocabularyMatchingPattern` vergeben (`0..1`).

### 4.3 URI-based Classification Vocabularies

Nach fachlicher Stabilisierung sollen `InterpretationProperty`, `VocabularyMatchingPattern`, `MatchDecision.decision`, Statuswerte und gegebenenfalls `preferredEntityType` als kleine kontrollierte Vokabulare in xTree gepflegt und über den LOD-Dienst mit auflösbaren URIs publiziert werden.

Empfohlene Metadaten je Eintrag:

| Attribute | Meaning |
|---|---|
| `uri` | Auflösbare URI |
| `code` | Stabiler maschinenlesbarer Code, z. B. `COMPOSITE_TERM` |
| `label` | Anzeigeform |
| `definition` | Normative Definition |
| `status` | z. B. `DRAFT`, `PROVISIONAL`, `STABLE`, `DEPRECATED` |

Sprechende URIs sind numerischen IDs vorzuziehen, beispielsweise:

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

Die konkrete URI-Struktur wird erst nach Stabilisierung der Vokabulare festgelegt.

## 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
        +sourceValueId
        +spanStart
        +spanEnd
        +sourceFragment
        +status
        +version
        +createdAt
    }

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

    class InterpretationProperty {
        <<classification>>
        +uri
        +code
        +label
        +definition
        +status
    }

    class ReconciliationResult {
        +id
        +success
        +matchingStrategy
        +confidence
        +note
        +createdAt
        +targetVocabularyUri
    }

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

    class VocabularyMatchingPattern {
        <<classification>>
        +uri
        +code
        +label
        +definition
        +status
    }

    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 "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 `SourceValue` wird in drei interpretierbare Fundstellen segmentiert. Für jede Fundstelle entsteht ein eigener `InterpretationGraph`:

```text
InterpretationGraph A
sourceFragment = "Bogen"
spanStart = first occurrence start
spanEnd = first occurrence end
└── InterpretationNode A0: "Bogen"

InterpretationGraph B
sourceFragment = "Bogen"
spanStart = second occurrence start
spanEnd = second occurrence end
└── InterpretationNode B0: "Bogen"

InterpretationGraph C
sourceFragment = "Bogen"
spanStart = third occurrence start
spanEnd = third occurrence end
└── InterpretationNode C0: "Bogen"
```

Jeder `InterpretationGraph` kann anschließend unabhängig erweitert, kontextualisiert und reconciliiert werden.

## 7. Use Case Mapping

| Use Case | `preferredEntityType` | Typical graph structure | Candidate type |
|---|---|---|---|
| Sachbegriff | `CONCEPT` | Meist ein `InterpretationGraph` mit einem Root Node und rekursiven Ableitungen | `CONCEPT` |
| Person | `PERSON` | Ein oder mehrere `InterpretationGraph` für Name oder Namensbestandteile unter Einbezug von Lebensdaten und Notes | `PERSON` |
| Ort | `PLACE` | Ein oder mehrere `InterpretationGraph` für Adresse, Ortsname und geografische Bestandteile | `PLACE` |
| Text | `MULTIPLE` | Mehrere `InterpretationGraph`, jeweils für einen Span beziehungsweise eine interpretierbare Fundstelle | Mixed |

## 8. Decisions and Deferred Design Questions

### 8.1 Decisions for v0.3

1. `ContextItem` gilt zunächst für den gesamten `SourceValue`. Eine feinere Zuordnung zu einzelnen `InterpretationGraph` oder `InterpretationNode` wird nicht modelliert.
2. `CandidateItem` wird fachlich primär über eine URI identifiziert.
3. Die fachliche Kardinalität `SourceValue 1 → 1..* InterpretationGraph` bleibt bestehen. Die nächste Reconcilix-Ausbaustufe erzeugt zunächst genau einen Graphen pro `SourceValue`.
4. Eine `InterpretationNode` besitzt in v0.3 höchstens eine Parent Node. Ein echter Many-to-many-Graph bleibt eine spätere Erweiterungsoption.
5. `preferredEntityType` ist ausschließlich Attribut des `SourceValue` und wird als Constraint nach unten vererbt. `CandidateItem.entityType` bezeichnet dagegen den tatsächlich festgestellten Typ.
6. Pro `ReconciliationResult` wird höchstens ein dominantes `VocabularyMatchingPattern` vergeben (`0..1`).
7. `InterpretationProperty` kann mehrfach pro `InterpretationNode` vergeben werden (`0..*`).
8. Das Domain Model bleibt fachlich breiter als die nächste Implementierungsstufe. Diese beschränkt sich zunächst auf `OpenRefine → Reconcilix → xTree/MCT` und `preferredEntityType = CONCEPT`.
9. `InterpretationProperty`, `VocabularyMatchingPattern`, `MatchDecision.decision`, Statuswerte und gegebenenfalls `preferredEntityType` sollen nach fachlicher Stabilisierung als kleine kontrollierte Vokabulare in xTree gepflegt und über den LOD-Dienst mit auflösbaren URIs publiziert werden.

### 8.2 Deferred Design Questions

Die folgenden Fragen werden bewusst nicht vor der ersten Implementierung abschließend entschieden:

1. Wie werden mehrere akzeptierte `CandidateItem` bei `preferredEntityType = MULTIPLE` in `MatchDecision` abgebildet?
2. Wann ist ein `InterpretationGraph` abgeschlossen und wann wird eine weitere `MatchingStrategy` ausgelöst?
3. Kann ein `InterpretationGraph` verschachtelte Subspans verwalten, oder wird für jeden Subspan grundsätzlich ein neuer Graph erzeugt?
4. Wann werden echte Many-to-many-Ableitungen zwischen `InterpretationNode` benötigt?
5. Welche Attribute werden nach der ersten Implementierung in ein separates Logical oder Technical Model verschoben?

Diese Fragen werden nach dem iterativen Pfad

```text
DM001 + ME001 + ME002
→ ADR
→ Implementierung des erweiterten Domain Model
→ Evaluation
→ nächste Modelliteration
```

anhand praktischer Erfahrungen erneut bewertet.

## 9. Initial Implementation Scope

Die nächste Ausbaustufe von Reconcilix setzt einen bewusst begrenzten Ausschnitt des Domain Model um:

```text
OpenRefine
→ Reconcilix
→ xTree / MCT
```

Für diese Stufe gelten insbesondere:

- `preferredEntityType = CONCEPT`,
- zunächst genau ein `InterpretationGraph` pro `SourceValue`,
- Candidate Discovery gegen xTree/MCT,
- Nutzung von Preferred Terms, Alternative Terms, Qualifiers und Hierarchierelationen,
- iterative Erweiterung erst nach Evaluation der implementierten Stufe.

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