Skip to content

[feature] Simplify and generalize the Relationship enum #519

@vcschapp

Description

The current Relationship enum in overture-schema-system has 7 domain-specific members (BELONGS_TO, BOUNDARY_OF, CAPITAL_OF, CAPITALLED_BY, CHILD_OF,
CONNECTS_TO, DESCENDANT_OF). This design has a few problems:

  1. It conflates structural category with domain semantics. CAPITAL_OF and CAPITALLED_BY are specific to the divisions theme but live in the shared system package.
  2. It doesn't scale. Every new kind of relationship across any theme requires adding a new enum member to the core system package.
  3. It mixes coupling strengths. There's no way to distinguish a lifecycle-dependent structural relationship (building part → building) from a loose peer reference (segment → connector) at the type level.

Proposed change

Replace the 7 members with 4 abstract semantic types that describe coupling strength rather than domain-specific meaning:

  • COMPOSITION — structural whole-part, lifecycle dependent
  • AGGREGATION — grouping without lifecycle dependency
  • HIERARCHY — organizational/classificatory nesting
  • ASSOCIATION — peer-level reference

Domain-specific meaning (e.g., "capital_of", "boundary_of") moves to an optional role field on the Reference annotation, allowing themes to express their semantics without modifying the core enum.

Motivation

  • Aligns with the relationship model proposed in Pydantic relationships #511
  • Makes the system package stable as new themes and relationship patterns are added
  • Provides a clear decision framework (diamond model) for schema authors choosing a relationship type

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions