Item Categories and Hierarchies

GPM uses two distinct but complementary concepts for organising items:

1. Item categories — groups of typed attributes that can be attached to items, defining what metadata an item can carry.
2. Catalogue hierarchy — a tree of CATEGORY-typed items linked by BELONGS_TO_CATEGORY relationships, defining where an item sits in the browsable catalogue.

The first answers "what can I say about this item?" The second answers "where does this item appear when a user browses the marketplace?"

Item categories (attribute groups)

An item category defines a logical group of attributes. For example, an "Insurance – Settlement" category groups settlement-related attributes, while an "Insurance – Benefits" category groups benefit coverage attributes.

Each category has a unique code within its tenant (e.g. INS_SETTLEMENT), a display name with internationalised translations, and an optional parent category for nested grouping. A display order controls how categories are sorted in the UI.

Categories are reference data — all authenticated users can read them, and unauthenticated marketplace users can also view them.

Insurance category examples

Code	Name
INS_SETTLEMENT	Settlement
INS_DEFINED_EVENTS	Defined Events
INS_BENEFITS	Benefits
INS_LEGAL_LIABILITY	Legal Liability
INS_OTHER_COVERAGE	Other Coverage
INS_FINANCIAL	Financial

These are examples from the standard insurance setup. Categories and their attributes are extensible, so other domains can define their own category groups and fields. Each category contains typed attribute definitions (see Attributes and Values).

Catalogue hierarchy

The browsable catalogue hierarchy is built from items with item_type = 'CATEGORY' connected by BELONGS_TO_CATEGORY relationships. This tree structure determines how users navigate the marketplace.

Hierarchy rules

• A category node is an item with item_type = 'CATEGORY'.
• Each item may have at most one BELONGS_TO_CATEGORY parent (single-parent constraint).
• The parent in a BELONGS_TO_CATEGORY relationship must have item_type = 'CATEGORY'.
• Cycles are prevented — the system walks ancestors before creating a relationship to detect loops.
• Once an item is a parent in BELONGS_TO_CATEGORY, its item_type cannot be changed away from CATEGORY.

These constraints guarantee that the hierarchy forms a valid forest (a collection of trees with no cycles).

Example category tree

The following seed category tree is an example catalogue structure:

CAT-ROOT (Service Categories)
├── CAT-HEALTH (Healthcare)
│   └── CAT-HEALTH-RAD (Radiology)
│       └── RAD-CT, RAD-MR, RAD-US, … (10 procedures)
├── CAT-INS (Insurance)
│   ├── CAT-INS-HOME (Home Insurance)
│   ├── CAT-INS-VEH (Vehicle Insurance)
│   ├── CAT-INS-HLTH (Health Insurance)
│   ├── CAT-INS-LIFE (Life & Income Insurance)
│   ├── CAT-INS-TRVL (Travel Insurance)
│   ├── CAT-INS-BUS (Business Insurance)
│   └── CAT-INS-PET (Pet Insurance)
└── CAT-BEAUTY (Self-Care & Beauty)
    ├── CAT-BEAUTY-HAIR (Hair Services)
    ├── CAT-BEAUTY-NAIL (Nail Services)
    ├── CAT-BEAUTY-SKIN (Skin & Beauty)
    └── CAT-BEAUTY-MASS (Massage)

Navigation

GPM provides hierarchy traversal for marketplace navigation, breadcrumbs, and administration:

Category children

Category children are returned in display order. This is used when a user clicks into a category in the marketplace to see what is inside.

Item ancestors

Item ancestor traversal walks BELONGS_TO_CATEGORY relationships upward from an item to the root. This powers breadcrumb navigation and CTA inheritance resolution.

Item descendants

Item descendant traversal walks BELONGS_TO_CATEGORY relationships downward from a category to all leaves. This is useful for retrieving every item within a category, including all nested sub-categories.

Category tree

The category tree returns the full category hierarchy with parent references and depth, providing a complete picture of the catalogue structure for administration and reporting.

Navigation data is available where catalogue information is public, so marketplace users can browse categories without needing to sign in.