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.

The CatalogItem interface

Every catalog entry, regardless of its specific 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.

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 — it returns false for system-managed items and for any item that other entities currently reference.

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.
textColor	HexColorCode	The text color for UI display.
backgroundColor	HexColorCode	The background color for UI display.
icon	String	A relative URL to the item's icon.

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.

See also

Page	Description
Catalog items	Core queries and mutations for managing catalogs and their items, plus 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).