Category Model Reference

Complete property reference for the ProductCategory model in Omnium, including all fields, data types, and usage notes.

This page provides a complete reference for the ProductCategory model used throughout Omnium.

Property Reference

Property	Type	Description
`id`	string	Computed. Unique identifier combining `categoryId` and `language` (e.g., `electronics_en`). Used as the document ID in storage.
`categoryId`	string	Required. The category identifier without language suffix. Shared across all language versions of the same category.
`name`	string	Display name of the category. Searchable field.
`description`	string	Short description of the category.
`parentId`	string	Reference to the parent category's `categoryId`. Null for root categories.
`language`	string	Language code (e.g., `en`, `no`, `sv`). Each language has a separate category document.
`sortIndex`	int	Display order within the parent category. Lower values appear first.
`isHidden`	bool	When true, the category is hidden from end users but still accessible via API.
`isMainCategory`	bool	Marks the category as a primary/root category.
`imageUrl`	string	URL for the category thumbnail or banner image.
`assets`	List<Asset>	Additional media assets associated with the category.
`properties`	List<PropertyItem>	Custom metadata as key-value pairs.
`metaTitle`	string	SEO page title for the category.
`metaDescription`	string	SEO meta description.
`metaKeywords`	string	SEO keywords (comma-separated).
`googleProductCategoryId`	string	Google Merchant Center category ID for product feeds.
`savedSearchId`	string	Links the category to a saved search for dynamic categories.
`additionalProductRatings`	List<RatingType>	Category-specific rating types that apply to products in this category.
`modified`	DateTime	Last modification timestamp.

ID Structure

Categories use a composite ID structure that combines the category identifier with the language:

{categoryId}_{language}

Examples:

electronics_en - Electronics category in English
electronics_no - Electronics category in Norwegian
clothing-mens-shirts_sv - Men's shirts category in Swedish

This structure allows:

The same logical category to exist with different content per language
Querying all languages of a category by categoryId
Unique document identification in storage

When assigning categories to products, use the categoryId (without language suffix). The system handles language-specific lookups based on the product's language.

Example Category Document

{
  "id": "mens-shirts_en",
  "categoryId": "mens-shirts",
  "name": "Men's Shirts",
  "description": "Dress shirts, casual shirts, and t-shirts for men",
  "parentId": "mens-clothing",
  "language": "en",
  "sortIndex": 100,
  "isHidden": false,
  "isMainCategory": false,
  "imageUrl": "https://cdn.example.com/categories/mens-shirts.jpg",
  "assets": [
    {
      "url": "https://cdn.example.com/categories/mens-shirts-banner.jpg",
      "purposeKey": "banner"
    }
  ],
  "properties": [
    {
      "name": "seasonalHighlight",
      "value": "Summer Collection"
    }
  ],
  "metaTitle": "Men's Shirts | Shop Dress & Casual Shirts",
  "metaDescription": "Browse our collection of men's shirts including dress shirts, casual button-downs, and t-shirts.",
  "metaKeywords": "mens shirts, dress shirts, casual shirts, t-shirts",
  "googleProductCategoryId": "212",
  "savedSearchId": null,
  "additionalProductRatings": [
    {
      "name": "fitRating",
      "displayName": "Fit",
      "maxValue": 5
    }
  ],
  "modified": "2024-01-15T10:30:00Z"
}

Properties Field

The properties field allows storing custom metadata on categories. Each property is a key-value pair:

"properties": [
  {
    "name": "bannerColor",
    "value": "#3498db"
  },
  {
    "name": "promotionText",
    "value": "20% off this week"
  },
  {
    "name": "displayStyle",
    "value": "grid"
  }
]

Common use cases:

UI configuration (colors, layouts)
Promotional content
Integration metadata
Custom filtering attributes

Assets Field

The assets field stores additional media beyond the main imageUrl:

"assets": [
  {
    "url": "https://cdn.example.com/banner.jpg",
    "purposeKey": "banner",
    "altText": "Summer collection banner"
  },
  {
    "url": "https://cdn.example.com/icon.svg",
    "purposeKey": "icon"
  },
  {
    "url": "https://cdn.example.com/mobile-banner.jpg",
    "purposeKey": "mobile-banner"
  }
]

Use purposeKey to identify asset types in your frontend application.

Additional Product Ratings

Categories can define rating types that apply to products within them:

"additionalProductRatings": [
  {
    "name": "comfort",
    "displayName": "Comfort",
    "maxValue": 5
  },
  {
    "name": "durability",
    "displayName": "Durability",
    "maxValue": 5
  }
]

Products in this category will have these rating types available in addition to any global rating configuration.

In Omnium's multi-tenant architecture, each tenant has completely separated data at the index level. There is no need to filter by tenant when querying categories - you automatically receive only your tenant's data.

The tenantId field is used internally for data isolation but does not need to be specified in API requests.