Catalogs

Explains catalogs as Business Data Repository reference data, including the CatalogItem interface, item origins, display metadata, and hierarchical items.

Catalogs are the reference data system of Business Data Repository. They provide structured, reusable lookup values (such as asset types or geo object types) that classify and annotate entities throughout the API. Rather than allowing freeform text, catalogs enforce standardized values, keeping data consistent, supporting filtering and reporting, and enabling localized display names.

Catalogs can be system (predefined) and user-created.

How catalogs work

Why use catalogs?

Without a shared reference system, properties like vehicle color, fuel type, or device status end up stored as freeform strings formatted in different ways by different users, in different languages, with inconsistent casing. Filtering for "all red vehicles" becomes unreliable when the value might be red, Red, or rouge. Creating a dedicated entity type for each such property solves the consistency problem, but requires separate backend and frontend work for every new property, making the resulting schema hard to manage.

Catalogs solve both problems at once. All reference data, whether platform-defined or workspace-specific, shares a single interface, a single set of queries, and predictable behavior. Adding a new lookup type doesn't require a new API entity: it's a new catalog, handled the same way as every other.

The CatalogItem interface

Every catalog entry, regardless of its type, implements the CatalogItem interface. This common structure means you work with catalog items the same way across the entire API.

Field	Type	Description
id	ID!	A globally unique identifier.
version	Int!	The version number for optimistic locking.
title	String!	The human-readable display name. Can be localized.
code	Code!	A machine-readable identifier, unique within the catalog scope.
order	Int!	The display order within the same level or category.
catalog	Catalog!	The catalog this item belongs to.
workspace	Workspace	The workspace that owns this item. null for system items.
meta	CatalogItemMeta!	Metadata, including origin, display properties, and deletion eligibility.

The code field uses the Code scalar: letters, digits, underscores, dots, and hyphens, compared without regard to case and stored as written. System-defined items use lower_snake_case codes (for example gps_tracker, active). A code generated from a title is lower_snake_case too, and a code you pass is stored as written. System item codes are stable across the platform (hardcoded and unchanging), making them safe to use as enum-like constants in business logic. Codes for user-created items are unique within the catalog and workspace.

Catalogs are catalog items

The Catalog type itself implements CatalogItem. A catalog is a named container that groups related items and belongs to a module; bdr is this API's own. This self-referential design means the API's meta-catalog, "the catalog of catalogs," is itself a catalog item.

Item origins

The CatalogItemMeta.origin field indicates how an item was created and determines whether it can be modified.

Origin	Description
SYSTEM	Predefined by the platform. Immutable and available to all workspaces.
PRESET	Created by Business Data Repository in the current workspace when the workspace was activated. Only asset types have this origin: the base types Workforce, Vehicle, and Cargo. The workspace owns them and can edit or delete them like its own items.
WORKSPACE	Created by the current workspace.

System items cannot be deleted or modified. meta.canBeDeleted is false for system items and true for every workspace item, PRESET items included. It doesn't check whether other entities reference the item.

Note that origin applies at the item level, not the catalog level. Some system catalogs, such as AssetType, accept workspace-created items alongside platform-defined ones. In those cases, the catalog itself has SYSTEM origin, while the items your workspace adds have WORKSPACE origin.

User-created catalogs

Workspaces can also create entirely custom catalogs for domain-specific lookup data that the platform doesn't provide, for example fuel types, concrete grades, or cargo classifications. Items in a user-created catalog belong exclusively to the workspace that created them. Use catalogCreate to create a catalog, then userCatalogItemCreate to populate it with items.

Display properties

All catalog items have optional display metadata in CatalogItemMeta that controls how they appear in client UI.

Field	Type	Description
description	String	A description of the item. Can be localized.
hidden	Boolean!	Whether the item is hidden from regular UI lists.

Hierarchical catalog items

Some catalog types support parent-child relationships via the HierarchicalCatalogItem interface, which adds a parent field pointing to the item's parent in the hierarchy. This allows building tree-structured lookup tables, such as a multi-level classification scheme for assets or devices. The specific type that implements this interface is UserCatalogItem, which also provides a paginated children field for traversing the tree downward.

See also

Catalog items: Core queries and mutations for managing catalogs and their items, including catalogCreate, userCatalogItemCreate, the CatalogItem interface, CatalogItemMeta, and shared input/output types.

Tags: Tag management for flexible, cross-entity labeling. Tags extend CatalogItem with an optional entityTypes constraint that limits which entity types a tag can be applied to.

System catalogs: System-defined catalog types that cannot be modified: Module, EntityType, and Country.

Catalog reference: A cross-reference of the remaining (non-tag and non-system) catalog types organized by their parent entity (devices, assets, geo objects, schedules, and others).