Hierarchy Definitions

Hierarchy definitions control how objects appear in the sidebar navigation tree. Every application package needs at least one hierarchy to make its objects navigable. Without a hierarchy, objects are accessible only through flat search results.

What a Hierarchy Defines

A hierarchy is an ordered sequence of levels from root to leaf. Each level maps to an objectType in the package. The level order determines the tree structure users see in the sidebar — the first level sits at the top, and each subsequent level nests beneath its parent.

The hierarchy asset declares:

• A unique key identifying the hierarchy within the package
• A display name shown in the UI when multiple hierarchies exist
• A type that determines rendering behavior
• An ordered levels array where each entry references an objectType

Hierarchy Types

Type	Behavior
default	Standard navigation tree. Levels are defined explicitly in the package and populated through user actions or data imports.
native	Platform-scanned structure. Levels are auto-populated from metadata discovered during connector scans. The tree reflects the physical structure of the scanned data source.

Most custom packages use default. Connector packages that scan external systems (databases, BI tools, file systems) use native to mirror the source structure automatically.

Level Properties

Each entry in the levels array configures one tier of the navigation tree.

Property	Type	Purpose
key	string	Unique identifier for this level within the hierarchy
name	string	Display name shown in the tree
type	string	The objectType key this level represents
hasFixedParent	boolean	Parent auto-assigned from hierarchy path. When true, creating an object at this level automatically sets its parent to the nearest ancestor in the tree.
hideIfEmpty	boolean	Hides the level in the tree when no objects exist at this tier
isMandatory	boolean	Objects at this level must have a value assigned. Prevents empty nodes in the hierarchy.

hasFixedParent

Root levels set hasFixedParent to false — they have no parent in the hierarchy. All levels below root should set it to true. This ensures that when objects are created or imported, the platform automatically establishes the parent-child relationship based on the tree position.

hideIfEmpty

Useful for leaf levels that may not exist in all branches. A database schema might have tables but no views. Setting hideIfEmpty: true on the views level prevents empty folders from cluttering the tree.

isMandatory

Marks a level as required in the hierarchy path. Objects created at mandatory levels must be assigned to a parent. Non-mandatory levels can be skipped when the hierarchy allows sparse trees.

Same-Level Nesting and Parent Locking

Two hierarchy-level properties control advanced nesting behavior:

Property	Effect
hasSameLevelParent	Allows objects at the same hierarchy level to nest under each other. Enables recursive structures like folder-within-folder.
disableParentUpdate	Locks parent assignment after object creation. Prevents users from moving objects between branches.

Setting hasSameLevelParent to true on a level means an object of that type can be a child of another object of the same type. A “folder” objectType could nest arbitrarily deep.

Setting disableParentUpdate to true is common for connector packages where the hierarchy reflects a scanned physical structure. Users should not rearrange database tables between schemas.

Connecting a Hierarchy to an Application

The application asset’s hierarchyDefinitions array links hierarchies to the application. Each entry specifies the hierarchy key and whether it is the default view.

{
  "key": "my_application",
  "name": "My Application",
  "hierarchyDefinitions": [
    {
      "hierarchyDefinitionKey": "default",
      "isDefault": true
    }
  ]
}

An application can reference multiple hierarchies. Users switch between them in the sidebar dropdown. The hierarchy with isDefault: true loads first.

Example: Connector Hierarchy

A database connector package with five levels — from server down to column:

{
  "key": "default",
  "name": "Default Hierarchy",
  "type": "default",
  "hasSameLevelParent": false,
  "levels": [
    { "key": "server", "name": "Server", "type": "server", "hasFixedParent": false, "hideIfEmpty": false, "isMandatory": true },
    { "key": "database", "name": "Database", "type": "database", "hasFixedParent": true, "hideIfEmpty": false, "isMandatory": true },
    { "key": "schema", "name": "Schema", "type": "schema", "hasFixedParent": true, "hideIfEmpty": true, "isMandatory": false },
    { "key": "table", "name": "Table", "type": "table", "hasFixedParent": true, "hideIfEmpty": true, "isMandatory": false },
    { "key": "column", "name": "Column", "type": "column", "hasFixedParent": true, "hideIfEmpty": true, "isMandatory": false }
  ],
  "translations": [{ "languageKey": "cs-CZ", "name": "Výchozí hierarchie" }]
}

Server and database are mandatory — every connector scan produces at least these two levels. Schema, table, and column use hideIfEmpty: true because not every database exposes all three tiers. The translations array provides localized names for the hierarchy itself.

Example: Business Hierarchy

A business glossary package with two levels — domain and term:

{
  "key": "business",
  "name": "Business Hierarchy",
  "type": "default",
  "hasSameLevelParent": false,
  "levels": [
    { "key": "domain", "name": "Domain", "type": "business_domain", "hasFixedParent": false, "hideIfEmpty": false, "isMandatory": true },
    { "key": "term", "name": "Term", "type": "business_term", "hasFixedParent": true, "hideIfEmpty": false, "isMandatory": false }
  ]
}

Domains are the root level. Terms nest under domains. Since hideIfEmpty is false on both levels, empty domains still appear in the tree — users can see and populate them.

Example: Recursive Hierarchy

A document management package where folders can nest inside other folders:

{
  "key": "documents",
  "name": "Document Hierarchy",
  "type": "default",
  "hasSameLevelParent": true,
  "levels": [
    { "key": "folder", "name": "Folder", "type": "doc_folder", "hasFixedParent": false, "hideIfEmpty": false, "isMandatory": false },
    { "key": "document", "name": "Document", "type": "doc_document", "hasFixedParent": true, "hideIfEmpty": true, "isMandatory": false }
  ]
}

Setting hasSameLevelParent to true at the hierarchy level allows folders to nest arbitrarily deep. A folder can be a child of another folder, creating structures like /Policies/HR/Onboarding/.

Multiple Hierarchies

An application can offer multiple hierarchy views of the same data. A data catalog might have a technical hierarchy (server > database > table) and a business hierarchy (domain > subdomain > asset).

{
  "key": "data_catalog_app",
  "name": "Data Catalog",
  "hierarchyDefinitions": [
    {
      "hierarchyDefinitionKey": "technical",
      "isDefault": true
    },
    {
      "hierarchyDefinitionKey": "business_view",
      "isDefault": false
    }
  ]
}

Users switch between hierarchies using the sidebar dropdown. Each hierarchy provides a different organizational perspective on the same set of objects. The default hierarchy loads on first navigation.

Only one hierarchy can be marked as default. If multiple entries set isDefault: true, the platform uses the first one in the array.

Relationship to objectTypeRelations

Hierarchy levels define the visual tree. The underlying data model uses objectTypeRelations to establish parent-child edges between object types. Each hierarchy level’s type must correspond to an objectType key, and the parent-child chain must be backed by core#isParentOf relations.

A five-level connector hierarchy requires four core#isParentOf relations:

Parent objectType	Child objectType
server	database
database	schema
schema	table
table	column

Without these relations, the hierarchy definition is structurally valid but objects cannot be assigned parents. The tree renders but remains flat.

Translations

Hierarchy names and level names support localization through the translations array. Each translation entry specifies a languageKey and the translated name.

{
  "translations": [
    { "languageKey": "cs-CZ", "name": "Obchodní hierarchie" },
    { "languageKey": "de-DE", "name": "Geschäftshierarchie" }
  ]
}

Translations apply to the hierarchy display name in the sidebar dropdown. Level names within the tree use the objectType’s own translations.

Gotchas