# Distinguishing Value, Type, and Relationship Conflicts in Semantica

> Understand Semantica's conflict detection. Learn to distinguish value, type, and relationship conflicts using the ConflictDetector class for robust data management.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: deep-dive
- Published: 2026-09-11

---

**Semantica's conflict detection engine recognizes five distinct conflict categories—value, type, relationship, temporal, and logical—through the ConflictDetector class, which groups entities by unique identifiers and compares properties, classifications, and edge attributes across multiple data sources.**

Semantica is an open-source knowledge graph framework that automatically surfaces data inconsistencies across heterogeneous sources. Its **conflict detection subsystem** centers on the `ConflictDetector` class, which analyzes entities from multiple origins to flag discrepancies in values, types, and relationships. Understanding how to distinguish value, type, and relationship conflicts enables developers to build more reliable data integration pipelines.

## Value Conflicts: When Properties Diverge

**Value conflicts** occur when two or more sources report the same property of the same entity with different literal values. For example, one source might list "Apple Inc." while another lists "Apple" for the same company entity.

### Detection Logic for Value Conflicts

In [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py), the detector groups incoming records by entity ID and compares property values for equality. When `detect_value_conflicts` is invoked with a specific property name—such as `detect_value_conflicts(entities, "name")`—it examines all values assigned to that property across sources. If multiple distinct values exist for the same entity-property pair, the system raises a `VALUE_CONFLICT`.

## Type Conflicts: Classification Discrepancies

**Type conflicts** arise when the same entity is classified under different semantic types across sources, such as being labeled as both `Company` and `Organization`. Unlike value conflicts, these focus on the entity's fundamental classification rather than individual attributes.

### How Type Conflicts Are Identified

The `detect_type_conflicts` method (lines 55-78 in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py)) extracts the `type` or `entity_type` field from all records sharing the same entity ID. It collects all observed type values and flags a conflict when more than one unique type appears. This routine incorporates a `self.progress_tracker` to provide real-time feedback when processing large datasets.

## Relationship Conflicts: Edge Inconsistencies

**Relationship conflicts** occur when connections between entities disagree on target IDs, predicates, or relationship-specific attributes. For instance, two sources might claim the same "parent-of" relationship points to different child entities.

### Relationship Conflict Detection

The `detect_relationship_conflicts` routine evaluates collections of relationship dictionaries, comparing source-specific IDs, predicates, and attributes like start/end dates. If two sources disagree on any component for the same relationship ID, the system produces a `RELATIONSHIP_CONFLICT`. This operates on the edges between entities rather than the entity nodes themselves.

## The Common Conflict Data Model

All conflict categories share a unified **`Conflict`** data model defined in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py) (lines 78-92). This dataclass stores:

- The conflicting values
- Provenance sources via `SourceReference` objects
- Confidence scores and severity levels
- Recommended remediation actions

When `track_provenance` is enabled, each conflict records originating sources through `SourceReference`, enabling downstream tools to trace which specific documents contributed the inconsistent data.

## Practical Implementation Examples

The public API in [`semantica/conflicts/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/methods.py) exposes `detect_conflicts`, which dispatches to the appropriate detector based on the `method` parameter.

### Detecting Value Conflicts

```python

# Detecting value conflicts on the 'name' property

from semantica.conflicts.methods import detect_conflicts

entities = [
    {"id": "1", "name": "Apple Inc.", "source": "doc1"},
    {"id": "1", "name": "Apple",      "source": "doc2"},
]
value_conflicts = detect_conflicts(entities, method="value", property_name="name")
print(value_conflicts[0].conflict_type)    # → value_conflict

```

### Detecting Type Conflicts

```python

# Detecting type conflicts

from semantica.conflicts.methods import detect_conflicts

entities = [
    {"id": "2", "type": "Company", "source": "doc1"},
    {"id": "2", "type": "Organization", "source": "doc2"},
]
type_conflicts = detect_conflicts(entities, method="type")
print(type_conflicts[0].conflict_type)    # → type_conflict

```

### Detecting Relationship Conflicts

```python

# Detecting relationship conflicts

from semantica.conflicts.methods import detect_conflicts

relationships = [
    {"id": "rel-1", "source": "doc1", "subject": "1", "predicate": "parent_of", "object": "2"},
    {"id": "rel-1", "source": "doc2", "subject": "1", "predicate": "parent_of", "object": "3"},
]
rel_conflicts = detect_conflicts([], method="relationship", relationships=relationships)
print(rel_conflicts[0].conflict_type)    # → relationship_conflict

```

## Summary

- **Value conflicts** indicate discrepancies in specific property values (e.g., different names for the same entity) while maintaining consistent entity types.
- **Type conflicts** signal fundamental classification disagreements where an entity is assigned multiple semantic types across sources.
- **Relationship conflicts** expose inconsistencies in graph edges, including differing target IDs or predicates for the same relationship.
- All conflicts are captured in a unified data model supporting provenance tracking via `SourceReference` and real-time progress monitoring.
- The detection logic resides primarily in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py), with the public API exposed through [`semantica/conflicts/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/methods.py).

## Frequently Asked Questions

### What is the difference between value conflicts and type conflicts in Semantica?

**Value conflicts** concern literal property values like strings or numbers assigned to an entity, whereas **type conflicts** involve the semantic classification of the entity itself. A value conflict might flag that one source calls an entity "Apple" and another "Apple Inc.," while a type conflict would flag that one source classifies it as a `Company` and another as an `Organization`. The detector handles these through separate routines—`detect_value_conflicts` for properties and `detect_type_conflicts` for classifications.

### How does Semantica track which source contributed a conflicting value?

When `track_provenance` is enabled, the conflict detector wraps source information in **`SourceReference`** objects (defined in [`semantica/conflicts/conflicts_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflicts_provenance.py)). Each conflict record includes provenance metadata identifying the specific documents or APIs that contributed the inconsistent values. This allows data engineers to trace conflicts back to their originating datasets for manual review or automated resolution strategies.

### Can the conflict detector handle temporal and logical inconsistencies in addition to value, type, and relationship conflicts?

Yes. The `ConflictType` enum in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py) (lines 68-76) defines five categories: `VALUE_CONFLICT`, `TYPE_CONFLICT`, `RELATIONSHIP_CONFLICT`, `TEMPORAL_CONFLICT`, and `LOGICAL_CONFLICT`. Temporal conflicts surface when time-based attributes clash (e.g., differing foundation years), while logical conflicts trigger when entities violate ontological rules (such as being both a `Person` and a `Location` simultaneously).

### What file contains the core detection logic for relationship conflicts?

The core logic for relationship conflict detection resides in **[`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py)**, specifically within the `detect_relationship_conflicts` method. This routine evaluates relationship dictionaries by comparing subject IDs, predicates, and object IDs across sources. The public API method `detect_conflicts` in [`semantica/conflicts/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/methods.py) provides the entry point for invoking this functionality with `method="relationship"`.