> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs.md).

# 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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitem) interface. This common structure means you work with catalog items the same way across the entire API.

<table><thead><tr><th width="129.88897705078125">Field</th><th width="166.55560302734375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>ID!</code></td><td>A globally unique identifier.</td></tr><tr><td><code>version</code></td><td><code>Int!</code></td><td>The version number for <a href="/docs/navixy-graphql-api/optimistic-locking.md">optimistic locking</a>.</td></tr><tr><td><code>title</code></td><td><code>String!</code></td><td>The human-readable display name. Can be localized.</td></tr><tr><td><code>code</code></td><td><a href="/docs/navixy-graphql-api/core-api-reference/common.md#code">Code</a>!</td><td>A machine-readable identifier, unique within the catalog scope.</td></tr><tr><td><code>order</code></td><td><code>Int!</code></td><td>The display order within the same level or category.</td></tr><tr><td><code>catalog</code></td><td><a href="/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#catalog">Catalog</a>!</td><td>The catalog this item belongs to.</td></tr><tr><td><code>workspace</code></td><td><a href="/docs/navixy-graphql-api/products/business-data-repository/api-reference/workspaces.md#workspace">Workspace</a></td><td>The workspace that owns this item. <code>null</code> for system items.</td></tr><tr><td><code>meta</code></td><td><a href="/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmeta">CatalogItemMeta</a>!</td><td>Metadata, including origin, display properties, and deletion eligibility.</td></tr></tbody></table>

The `code` field uses the [Code](/docs/navixy-graphql-api/core-api-reference/common.md#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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#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.

<table><thead><tr><th width="249.55560302734375">Origin</th><th>Description</th></tr></thead><tbody><tr><td><code>SYSTEM</code></td><td>Predefined by the platform. Immutable and available to all workspaces.</td></tr><tr><td><code>PRESET</code></td><td>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.</td></tr><tr><td><code>WORKSPACE</code></td><td>Created by the current workspace.</td></tr></tbody></table>

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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/assets.md#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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#catalogcreate) to create a catalog, then [userCatalogItemCreate](/docs/navixy-graphql-api/products/business-data-repository/api-reference/actors/users.md#usercatalogitemcreate) to populate it with items.

### Display properties

All catalog items have optional display metadata in [CatalogItemMeta](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#catalogitemmeta) that controls how they appear in client UI.

<table><thead><tr><th width="183.22216796875">Field</th><th width="166.4444580078125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>description</code></td><td><code>String</code></td><td>A description of the item. Can be localized.</td></tr><tr><td><code>hidden</code></td><td><code>Boolean!</code></td><td>Whether the item is hidden from regular UI lists.</td></tr></tbody></table>

### Hierarchical catalog items

Some catalog types support parent-child relationships via the [HierarchicalCatalogItem](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md#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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/actors/users.md#usercatalogitem), which also provides a paginated `children` field for traversing the tree downward.

## See also

[Catalog items](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-items.md): Core queries and mutations for managing catalogs and their items, including `catalogCreate`, `userCatalogItemCreate`, the `CatalogItem` interface, `CatalogItemMeta`, and shared input/output types.

[Tags](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/tags.md): 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](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/system.md): System-defined catalog types that cannot be modified: `Module`, `EntityType`, and `Country`.

[Catalog reference](/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs/catalog-reference.md): 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/navixy-graphql-api/products/business-data-repository/api-reference/catalogs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.