Entity Hierarchy & Field Inheritance

Model parent-child relationships and inherit attributes down organizational trees.

Overview

Many real-world entities exist in hierarchies: companies have departments, departments have employees, hospitals have facilities, facilities have practitioners. Kanoniv's hierarchy feature lets you define these relationships in your spec so that child entities can inherit attributes from their parents during reconciliation.

Cloud Feature

Hierarchy configuration requires the Cloud tier.

Spec Configuration

Add a hierarchy block to your entity definition:

entity:
  name: employee
  description: Employee identity with org hierarchy
  hierarchy:
    parent_field: department_id
    depth: 3
    inheritance:
      - industry
      - region
      - compliance_tier

Fields

Field	Type	Default	Description
parent_field	string	(required)	Field in the source data that references the parent entity
depth	int	5	Maximum tree traversal depth
inheritance	string[]	[]	Fields inherited from parent to child entities

How It Works

Before reconciliation begins, the engine builds a parent-child tree from the parent_field references and propagates inherited fields downward:

┌────────────────────────────────────────┐
│           Acme Corp (root)             │
│  industry: "technology"                │
│  region: "north_america"               │
│  compliance_tier: "soc2"               │
├────────────────────┬───────────────────┤
│                    │                   │
▼                    ▼                   │
┌──────────────┐  ┌──────────────┐       │
│ Engineering  │  │ Sales        │       │
│ dept_id: D1  │  │ dept_id: D2  │       │
│              │  │              │       │
│ Inherits:    │  │ Inherits:    │       │
│  industry ✓  │  │  industry ✓  │       │
│  region ✓    │  │  region ✓    │       │
│  compliance  │  │  compliance  │       │
│  _tier ✓     │  │  _tier ✓     │       │
├──────────────┤  └──────────────┘       │
│              │                         │
▼              ▼                         │
┌──────────┐ ┌──────────┐               │
│ Alice    │ │ Bob      │               │
│ emp: E1  │ │ emp: E2  │               │
│ dept: D1 │ │ dept: D1 │               │
│          │ │          │               │
│ Inherits:│ │ Inherits:│               │
│ industry,│ │ industry,│               │
│ region,  │ │ region,  │               │
│ comp_tier│ │ comp_tier│               │
└──────────┘ └──────────┘               │
                                        │
└────────────────────────────────────────┘

Inherited fields are available during matching and survivorship, just like directly-mapped attributes. If a child entity has its own value for an inherited field, the child's value takes precedence.

Full Example

api_version: kanoniv/v2
identity_version: employee_v2

entity:
  name: employee
  description: Enterprise employee resolution with org hierarchy
  hierarchy:
    parent_field: department_id
    depth: 3
    inheritance:
      - industry
      - region
      - compliance_tier

sources:
  - name: hr
    adapter: postgres
    location: hr.employees
    primary_key: employee_id
    attributes:
      email: work_email
      name: full_name
      department_id: dept_id
      title: job_title

  - name: directory
    adapter: postgres
    location: corp.directory
    primary_key: dir_id
    attributes:
      email: email
      name: display_name
      department_id: org_unit_id

  - name: org_structure
    adapter: postgres
    location: hr.departments
    primary_key: dept_id
    attributes:
      department_id: id
      industry: vertical
      region: geo_region
      compliance_tier: compliance_level

rules:
  - type: exact
    name: email_match
    field: email
    weight: 1.0
  - type: similarity
    name: name_match
    field: name
    algorithm: jaro_winkler
    threshold: 0.88
    weight: 0.7
  - type: exact
    name: dept_match
    field: department_id
    weight: 0.3

decision:
  thresholds:
    match: 0.9
    review: 0.7

Use Cases

Company Hierarchy

A common pattern for B2B identity resolution where subsidiary companies inherit attributes from the parent:

entity:
  name: company
  hierarchy:
    parent_field: parent_company_id
    depth: 4
    inheritance:
      - industry_vertical
      - headquarters_country

Healthcare Facility Hierarchy

Practitioners inherit facility-level compliance and network attributes:

entity:
  name: practitioner
  hierarchy:
    parent_field: facility_id
    depth: 2
    inheritance:
      - network_id
      - accreditation_status
      - state_license_region

Limitations

Maximum Depth

The depth parameter is capped at a system maximum of 10 levels. The validator rejects specs that exceed this limit. Deeper hierarchies should be flattened before reconciliation.

Cycle Detection

The engine detects cycles in the parent-child graph during tree construction. If a cycle is detected (e.g., A → B → C → A), the offending edge is dropped and a warning is logged. Reconciliation continues with the acyclic portion of the tree.

Field Precedence

When a child entity has a direct value for an inherited field, the child's own value always wins. Inheritance only fills in fields that would otherwise be null on the child.

TIP

Start with a small depth (2-3) and increase only if needed. Deeper hierarchies increase compilation time and memory usage proportionally.

Next Steps

• Compliance & PII Masking: Combine hierarchy with compliance frameworks
• Spec Governance: Full annotated spec reference