Catalogs

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

Navixy Repository API is a work in progress. This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.

Catalogs are the reference data system of Navixy Repository API. 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.

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 organization-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.
organization	Organization	The organization 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, a case-insensitive alphanumeric identifier. System-defined items follow UPPER_SNAKE_CASE (e.g., DEVICE_TYPE, ACTIVE), while user-created items can use format. 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 organization.

Catalogs are catalog items

The Catalog type itself implements CatalogItem. A catalog is a named container that groups related items and is associated with a system module (such as repo, fleet_management, or iot). 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 organizations.
ORGANIZATION	Created by the current organization.
PARENT_ORGANIZATION	Inherited from a parent organization in the dealer hierarchy.

System items cannot be deleted or modified. The meta.canBeDeleted field reflects whether a given item is eligible for deletion, returning false for system-managed items and for any item referenced by other entities.

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

User-created catalogs

Organizations 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 organization that created them. Use catalogCreate to create a catalog, then userCatalogItemCreate to populate it with items.

Display properties

All catalog items carry 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 exposes 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).