Item Relationships
Items in the GPM module are connected to each other through directed relationships. Each relationship links a child item to a related item with a typed relationship. The most important type is BELONGS_TO_CATEGORY, which builds the catalogue hierarchy, but the system supports additional types for substitutes, accessories, and other associations.
BELONGS_TO_CATEGORY
This is the primary relationship type. It connects any item to a parent category node, building the tree structure that determines how users browse the marketplace.
The system enforces several constraints to keep the hierarchy valid:
| Rule | Effect |
|---|---|
| Parent must be a CATEGORY | The related item must have item_type = 'CATEGORY' |
| Single parent per child | Each item can belong to at most one category |
| No cycles | The system walks ancestors before creating a relationship to detect loops |
| No self-references | An item cannot be its own parent |
| Parent type is immutable | Once an item is a parent, its type cannot be changed away from CATEGORY |
These constraints guarantee that BELONGS_TO_CATEGORY edges form a valid forest — a collection of trees with no cycles or multi-parent situations.
Other relationship types
Additional relationship types, such as substitutes, accessories, and bundles, are examples. The list is extensible, and unlike BELONGS_TO_CATEGORY, these types do not have single-parent or cycle constraints — an item can have multiple relationships of other types.
Two boolean flags support order-modification semantics:
- add_item_to_order — whether the related item should be added to an order alongside the original
- remove_item_from_order — whether the original item should be removed from an order
For example, a substitute relationship could be configured to add the substitute to the order and remove the original item, enabling one-click product swaps.
Examples
Insurance
Insurance service items are linked to their parent categories via BELONGS_TO_CATEGORY. For example, home insurance products are linked to CAT-INS-HOME.
Radiology
Ten radiology procedures (RAD-CT, RAD-MR, RAD-US, etc.) are linked to CAT-HEALTH-RAD via BELONGS_TO_CATEGORY, placing them under the Radiology sub-category of Healthcare.
Access control
Relationships are treated as reference data. Marketplace users can read public relationships for catalogue navigation. Authorised organisation users can create and update relationships within their tenant.