Distinguishing Value, Type, and Relationship Conflicts in Semantica

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, 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) 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 (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 exposes detect_conflicts, which dispatches to the appropriate detector based on the method parameter.

Detecting Value Conflicts

# 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

# 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

# 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, with the public API exposed through 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). 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 (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, 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 provides the entry point for invoking this functionality with method="relationship".

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}