Catalog and Category

The Catalog structure is the foundation of the Catalog module and follows TM Forum catalog-management terminology.

• A Catalog is the root business container.
• A Category groups entries in logical containers and supports hierarchy.
• A Specification (described in the next document) is attached to a category and carries the detailed definition.

This document starts with business meaning and TM Forum-aligned terms, then provides full field-level references.

---

1. Business Meaning

1.1 What a Catalog Represents

A catalog is the top-level business boundary for a coherent offer domain.

TM Forum wording:

• TMF620 (ProductCatalog) describes catalog as a collection of product offerings for a target channel/context.
• TMF633 (ServiceCatalog) describes catalog as the root entity that groups service specifications made visible through service candidates.
• TMF634 (ResourceCatalog) describes catalog structures used to organize resource candidates/specifications for technical resource domains.

In tSM, Catalog is used as a generalized catalog root across multiple domains (PRODUCT, SERVICE, RESOURCE, MATERIAL, SKILL, WORK, PRICELIST, OTHERS).

Business responsibilities of catalog:

• define domain classification (catalogType),
• define lifecycle and release visibility (lifecycleStatus, validity interval),
• provide category-level defaults (entityCatalogCategorySpecId),
• provide project-level extension metadata (config, dataTags, localizationData),
• separate governance and ownership between catalog domains.

Typical domain usage:

• PRODUCT: commercial product portfolio.
• SERVICE: technical service portfolio.
• RESOURCE: logical/physical resource portfolio.
• MATERIAL: stock/material portfolio.
• SKILL and WORK: workforce capability and work-definition portfolio.
• PRICELIST: pricing-oriented structures.

1.2 What a Category Represents

A category is a hierarchical grouping unit under one catalog.

TM Forum wording:

• TMF620 category groups product offerings and can contain subcategories.
• TMF633 service category groups service candidates and can contain subcategories.

In tSM, category acts as the main taxonomy node for grouping specifications and controlling structural navigation.

Business purpose in tSM:

• structure large catalog spaces into manageable trees,
• scope specification placement,
• control navigation, filtering, and business segmentation,
• carry category-level dynamic metadata (chars),
• provide inheritance boundary for configuration profiles and UI forms.

Category can be root-level or nested (parent) and can expose expanded parent/catalog objects for read scenarios.

1.3 Configuration Profile Meaning (Entities & Characteristics Pattern)

Catalog/Category are not only structural nodes. They also define which dynamic business attributes are available and how they are rendered.

• Catalog.entityCatalogCategorySpecId defines the configuration profile for categories in this catalog. This means category chars are governed by that profile and the profile defines category create/detail forms. Business use case: add category-level configuration like market segment, target customer segment, or regional scope.

• Category.entitySpecificationSpecId defines the configuration profile for specifications created in this category. This means specification chars are governed by the category-selected profile. Business use case: define product/service-level attributes like available speed, segment, provisioning options, or regional availability.

Important distinction:

• attributes defined by Category.entitySpecificationSpecId are specification-level attributes (shared by all instances of that specification),
• instance-specific runtime values (for example IP address, serial number, line state) belong to inventory-level entities, not to catalog specification configuration.

1.4 Typical Structural Flow

1. Create catalog with catalogType, lifecycleStatus, and validity.
2. Define root categories for business segmentation.
3. Add subcategories for deeper taxonomy.
4. Assign category-level profile and dynamic metadata.
5. Place specifications into target categories.
6. Publish/activate through lifecycle and validity governance.

1.5 TM Forum to tSM Terminology Mapping

TM Forum Term	tSM Equivalent	Notes
ProductCatalog (TMF620) / ServiceCatalog (TMF633) / ResourceCatalog (TMF634)	Catalog	tSM unifies catalog concepts across domains.
Category / ServiceCategory	Category	Hierarchical grouping unit under catalog.
ProductOffering / ServiceCandidate	Specification usage context	In tSM, these publication/use patterns are typically realized through specification placement, relationships, and downstream module behavior.
ProductSpecification / ServiceSpecification	Specification	Detailed definition template (covered in next document).

1.6 Why This Model Works for BSS/OSS

• separates commercial and technical domains while keeping a unified API model,
• supports large catalogs through category tree decomposition,
• allows controlled publication via lifecycle and validity intervals,
• keeps extension in metadata/configuration instead of schema branching,
• stays close to TM Forum conceptual model while remaining implementation-pragmatic.

---

2. Structural Behavior and Rules

• One category belongs to exactly one catalog (entityCatalog).
• Category hierarchy is self-referential via parent.
• Catalog and category validity windows limit active usage and publication period.
• Category metadata (chars) is configuration-driven and can evolve without schema migrations.
• Search/indexing typically differentiates category and specification via EntityTypeElastic.

2.1 Lifecycle and Publication Semantics

• lifecycleStatus controls governance state (for example draft/active/retired patterns, depending on configured status table).
• validityFrom/validityTo controls time-bound availability.
• valid represents computed runtime validity result.

Both status and validity should be treated together when deciding whether a catalog/category is operationally usable.

2.2 Root and Tree Semantics

• In TM Forum, categories have explicit root semantics (isRoot in TMF models).
• In tSM, root is represented structurally by absence of parent.
• Tree traversal and expansion are supported via parent, parentExpanded, and catalogExpanded.

2.3 Catalog.config Governance

Catalog.config can contain any additional JSON attributes needed by project/business logic.

To keep consistent UI and validation across catalogs:

• define a system form with code Catalog.Config,
• use that form as the canonical JSON structure and UI contract for the config payload.

This keeps configuration flexible but still controlled and understandable for administrators.

2.4 TM Forum References

• TMF620 Product Catalog Management API v5 (OpenAPI)
• TMF633 Service Catalog Management API v4 (Swagger)
• TMF634 Resource Catalog Management API v5 (OpenAPI)

---

3. Entity Reference: Catalog (Catalog)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Catalog primary key. Can be client-provided UUIDv4 or generated by tSM.
name	String	Yes	No	Human-readable catalog name.
code	String	Yes	No	Technical/business key. Should use ASCII without spaces.
validityFrom	Date	No	No	Catalog validity start.
validityTo	Date	No	No	Catalog validity end.
dataTags	List<String>	No	No	Optional labels/tags for classification and filtering.
catalogType	CatalogType	Yes	No	Classification of catalog domain. For utilization semantics see TMF620 ProductCatalog, TMF633 ServiceCatalog, and TMF634 ResourceCatalog references.
entityCatalogCategorySpecId	UUID	No	No	Configuration profile for categories in this catalog (Entities & Characteristics pattern). Defines which category characteristics belong here and how category create/detail forms are rendered.
config	Map<String, Any?>	No	No	Free JSON configuration payload. Recommended governance: define system form Catalog.Config as the canonical structure and UI for this field.
description	String	No	No	Optional catalog description.
localizationData	LocalizationData	No	No	Localized values for selected fields.
lifecycleStatus	String	Yes	No	Lifecycle status code (FK EntityCatalogStatus.code).
priceBook	Boolean	No	No	Price books are not currently supported as a dedicated capability in tSM. Model this using pricing settings and/or the characteristics pattern.

3.1 Enum Reference: CatalogType

Value	Meaning
PRODUCT	Product catalog classification. See TMF620 ProductCatalog for reference semantics.
SERVICE	Service catalog classification. See TMF633 ServiceCatalog for reference semantics.
RESOURCE	Resource catalog classification. See TMF634 ResourceCatalog for reference semantics.
MATERIAL	Material/asset catalog.
SKILL	Skill-definition catalog.
WORK	Work/task catalog.
PRICELIST	Pricing-oriented catalog.
OTHERS	Generic/other domain catalog.

---

4. Entity Reference: Category (Category)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Category primary key. Can be provided or generated.
name	String	Yes	No	Category display name.
code	String	Yes	No	Category technical code.
entitySpecificationSpecId	UUID	No	No	Configuration profile for specifications in this category (Entities & Characteristics pattern). Defines which specification characteristics belong here and how specification create/detail UI is rendered. These are specification-level attributes shared by all instances; instance-specific runtime values are stored at inventory level.
chars	TsmChars	No	No	Dynamic category attributes (characteristics map).
entityCatalog	String	Yes	No	Owning catalog code (FK EntityCatalog.code).
catalogExpanded	Catalog	No	Yes	Expanded owning catalog object (when expansion is requested).
dataTags	List<String>	No	No	Optional labels/tags.
description	String	No	No	Category description.
parent	String	No	No	Parent category code (FK self.code).
parentExpanded	Category	No	Yes	Expanded parent category object (when expansion is requested).
instancePriv	List<String>	No	No	Instance-level privilege payload.
validityFrom	Date	No	No	Category validity start.
validityTo	Date	No	No	Category validity end.
sortOrder	Int	No	No	Ordering value for UI/tree rendering.
icon	String	No	No	Optional UI icon identifier.
processingData	ProcessingData	No	Write-only	Transient processing context for runtime processing; not stored as standard business attributes.

4.1 Enum Reference: CategoryExpand

Value	Meaning
PARENT	Expand parent category object.
CATALOG	Expand owning catalog object.

---

5. Supporting Entities and Enums

5.1 Catalog Status Registry (EntityCatalogStatus)

Configurable code table for catalog lifecycle statuses.

Field	Type	Required	Read-only	Description
id	UUID	No	No	Status record primary key.
code	String	Yes	No	Technical status code.
name	String	Yes	No	User-facing status name.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Status description.
localizationData	LocalizationData	No	No	Localized labels/descriptions.
dataTags	List<String>	No	No	Optional labels.
config	Map<String, Any?>	No	No	Additional configuration payload.

5.2 Search Discriminator (EntityTypeElastic)

Value	Meaning
CATEGORY	Search/index scope is category documents.
SPECIFICATION	Search/index scope is specification documents.