5.215 min read

Catalog Management APIs

The Catalog Management APIs are the design-time foundation of a catalog-driven architecture. They manage the blueprints -- the product offerings, service specifications, and resource specifications -- that every runtime system depends on. Without well-managed catalogs, ordering, fulfilment, and inventory systems have nothing to instantiate.

Three APIs form the catalog triad: TMF620 (Product Catalog), TMF633 (Service Catalog), and TMF634 (Resource Catalog). Together, they define the complete specification hierarchy from commercial product down to network resource.

Catalog-Driven Architecture

In a catalog-driven architecture, runtime systems (ordering, activation, billing) never hard-code product or service logic. Instead, they read specifications from the catalog at runtime and use those specifications to drive behaviour. This means new products can be launched by catalog configuration, not code changes.

The catalog is the single most important system in a modern BSS/OSS stack. Get the catalog wrong, and every downstream system inherits the confusion.
— Common telco architecture principle

TMF620: Product Catalog Management

TMF620 -- Product Catalog Management

TMF620 manages the commercial product catalog -- the set of product offerings, product specifications, and categories that define what a telco sells to its customers. This is the BSS-domain catalog that drives CPQ, digital channels, and order capture.

TMF620 manages two core concepts: the ProductSpecification (the blueprint for a type of product) and the ProductOffering (a saleable packaging of one or more specifications with pricing, eligibility, and channel rules).

Key Resources in TMF620

TMF620 Core Resources

Resource	Purpose	Key Attributes
ProductOffering	A saleable item in the catalog with pricing and eligibility	name, description, lifecycleStatus, validFor, productOfferingPrice, productSpecification, channel, place
ProductSpecification	The blueprint defining the structure of a product type	name, brand, productNumber, productSpecCharacteristic, resourceSpecification, serviceSpecification
Category	A classification grouping for offerings	name, description, parentId, isRoot, productOffering
ProductOfferingPrice	Pricing structure for an offering	priceType (recurring/oneTime/usage), price, pricingLogicAlgorithm, validFor
Catalog	A named collection of offerings (e.g., Retail, Wholesale)	name, description, lifecycleStatus, category, relatedParty

TMF620 Operations

GET /productOffering -- List/query product offerings (with filtering)
GET /productOffering/{id} -- Retrieve a specific offering
POST /productOffering -- Create a new offering
PATCH /productOffering/{id} -- Update an offering (partial)
DELETE /productOffering/{id} -- Remove an offering
GET /productSpecification -- List/query product specifications
POST /productSpecification -- Create a specification
GET /category -- List catalog categories
POST /hub -- Register for event notifications

TMF620 in Action: Launching a New Broadband Product

To launch "Fibre Max 1Gbps": (1) POST /productSpecification to create the "Fixed Broadband" spec with characteristics like speed, data cap, and contract term. (2) POST /productOffering referencing that specification, with pricing (e.g., $89/month recurring), eligibility rules (e.g., available in fibre coverage areas), and channel visibility (e.g., visible in online, retail, and agent channels). (3) The offering is now queryable by digital channels via GET /productOffering?lifecycleStatus=Active.

TMF633: Service Catalog Management

TMF633 -- Service Catalog Management

TMF633 manages the service catalog -- the set of service specifications that define Customer-Facing Services (CFS) and Resource-Facing Services (RFS). This is the OSS-domain catalog that drives service order management and orchestration. Service specifications describe WHAT services exist and HOW they decompose.

The service catalog bridges the commercial and technical worlds. Product specifications reference service specifications (CFS), which in turn decompose into lower-level service specs (RFS). This decomposition chain is what enables automated fulfilment.

Key Resources in TMF633

TMF633 Core Resources

Resource	Purpose	Key Attributes
ServiceSpecification	Blueprint for a service type (CFS or RFS)	name, description, lifecycleStatus, serviceSpecCharacteristic, resourceSpecification, serviceSpecRelationship
ServiceCandidate	A pointer from a catalog to a specification	name, description, serviceCatalog, serviceSpecification
ServiceCatalog	A named collection of service specifications	name, description, lifecycleStatus, category, relatedParty
ServiceCategory	Classification grouping for service specs	name, description, isRoot, parentId, serviceCandidate

TMF633 Operations

GET /serviceSpecification -- List/query service specifications
GET /serviceSpecification/{id} -- Retrieve a specific specification
POST /serviceSpecification -- Create a new service specification
PATCH /serviceSpecification/{id} -- Update a specification
DELETE /serviceSpecification/{id} -- Remove a specification
GET /serviceCandidate -- List service candidates in a catalog
GET /serviceCatalog -- List available service catalogs
POST /hub -- Register for event notifications

CFS and RFS in the Service Catalog

A service catalog for broadband might contain: CFS:Internet-Access (with characteristics: downloadSpeed, uploadSpeed, dataAllowance) which has serviceSpecRelationship links to RFS:GPON-Bearer, RFS:VLAN-Assignment, RFS:IP-Profile, and RFS:QoS-Profile. The decomposition rules in these relationships tell Service Order Management which RFS instances to create when a CFS is ordered.

TMF634: Resource Catalog Management

TMF634 -- Resource Catalog Management

TMF634 manages the resource catalog -- the set of resource specifications that define the physical and logical resources available in the network. Resource specifications describe the types of equipment, logical elements, and configurations that RFS instances consume.

Resource specifications are the lowest level of the catalog hierarchy. They describe the types of resources (e.g., "OLT Port", "VLAN", "IP Address Pool") that the network can provide. Resource inventory (TMF639) then tracks the instances of these types.

Key Resources in TMF634

TMF634 Core Resources

Resource	Purpose	Key Attributes
ResourceSpecification	Blueprint for a resource type (physical or logical)	name, description, lifecycleStatus, resourceSpecCharacteristic, resourceSpecRelationship, @type
ResourceCandidate	A pointer from a catalog to a resource specification	name, description, resourceCatalog, resourceSpecification
ResourceCatalog	A named collection of resource specifications	name, description, lifecycleStatus, category, relatedParty
ResourceCategory	Classification grouping for resource specs	name, description, isRoot, parentId, resourceCandidate

Physical vs Logical Resource Specifications

TMF634 uses the @type polymorphism mechanism to distinguish between PhysicalResourceSpecification and LogicalResourceSpecification. Physical specs describe tangible equipment (routers, OLTs, ONTs), while logical specs describe configurable elements (VLANs, IP pools, QoS policies).

Physical resource specifications model network equipment and infrastructure. They typically include attributes like vendor, model, firmware version, form factor, port count, and power consumption.

OLT (Optical Line Terminal) -- with port types, capacity, supported splitter ratios
ONT (Optical Network Terminal) -- with ethernet ports, WiFi capability, POTS ports
Router -- with interface types, forwarding capacity, supported protocols
Switch -- with port density, VLAN support, stacking capability
Antenna/Radio Unit -- with frequency bands, MIMO configuration, power output

Comparing the Three Catalog APIs

The three catalog APIs follow a consistent pattern but serve different domains and audiences. Understanding the parallels and differences is key to working with catalog-driven architectures.

Catalog API Comparison

Aspect	TMF620 (Product)	TMF633 (Service)	TMF634 (Resource)
Domain	BSS -- Commercial	OSS -- Service	OSS -- Resource
Primary audience	Product managers, channel teams	Service architects, SOM teams	Network engineers, ROM teams
Core specification	ProductSpecification	ServiceSpecification	ResourceSpecification
Core saleable/usable entity	ProductOffering	ServiceCandidate	ResourceCandidate
Pricing model	Yes -- ProductOfferingPrice	No -- pricing is at product level	No -- pricing is at product level
Decomposition target	Links to ServiceSpec (CFS)	Links to ResourceSpec (RFS)	Links to physical/logical resources
Lifecycle states	In Study, In Design, Active, Retired, Obsolete	In Study, In Design, Active, Retired, Obsolete	In Study, In Design, Active, Retired, Obsolete
Design-time vs Runtime	Design-time (defines what can be sold)	Design-time (defines what can be delivered)	Design-time (defines what can be allocated)
Channel visibility	Yes -- channel, place, eligibility rules	Not directly channel-facing	Not directly channel-facing
Typical system owner	Product Catalog / CPQ system	Service Catalog / Service Design tool	Resource Catalog / Network Design tool

Design-Time vs Runtime: How Catalogs Drive Execution

A critical distinction in catalog-driven architecture is between design-time (when specifications are created and published) and runtime (when those specifications are instantiated as actual orders, services, and resources). The catalog APIs are design-time APIs; the ordering and inventory APIs are runtime APIs.

Think of the catalog as a restaurant menu (design-time) and the order as what you actually choose from the menu (runtime). The menu defines what is possible; the order captures what is happening. The catalog defines "Fixed Broadband 100Mbps" as an option; the order says "Customer John Smith wants Fixed Broadband 100Mbps at 42 Oak Street."

This is the Specification / Instance pattern, fundamental to TM Forum modeling:

ProductSpecification (TMF620) -> Product instance (TMF637)
ServiceSpecification (TMF633) -> Service instance (TMF638)
ResourceSpecification (TMF634) -> Resource instance (TMF639)

The specification defines the type (attributes, constraints, relationships). The instance represents a specific occurrence with concrete values. Specifications are shared across all customers; instances are per-customer (or per-allocation).

In a mature catalog-driven architecture, the fulfilment chain reads specifications from catalogs to drive every decision:

COM reads ProductSpecification to validate order items and determine required characteristics
SOM reads ServiceSpecification to decompose CFS into RFS and determine orchestration steps
ROM reads ResourceSpecification to identify resource types needed and allocation rules
Activation reads ResourceSpecification to generate device-level configuration templates

This means a new product can be launched entirely through catalog configuration: define the specs, define the decomposition rules, and the runtime systems automatically know how to fulfil it.

Cross-Catalog Relationships

The three catalog APIs do not operate in isolation. They form a linked hierarchy through cross-references:

Catalog Linkage Chain

Product Specification

TMF620 -- Product Catalog

Created in TMF620. Contains a serviceSpecification reference pointing to the CFS that realises this product.

Service Specification (CFS)

TMF633 -- Service Catalog

Created in TMF633. Contains serviceSpecRelationship entries pointing to RFS specifications. Also contains resourceSpecification references for any resources directly linked to the CFS.

Service Specification (RFS)

TMF633 -- Service Catalog

Also in TMF633. Contains resourceSpecification references pointing to the specific resource types each RFS requires.

Resource Specification

TMF634 -- Resource Catalog

Created in TMF634. Defines the physical or logical resource type with its characteristics, constraints, and relationships to other resources.

Cross-Catalog Integrity

A common pitfall is breaking cross-catalog references. If you retire a ServiceSpecification in TMF633 that is still referenced by active ProductSpecifications in TMF620, downstream systems will fail when they try to decompose orders. Catalog lifecycle management must be coordinated across all three catalogs. Most mature implementations enforce referential integrity rules or use lifecycle state checks to prevent orphaned references.

Catalog Event Notifications

All three catalog APIs support the standard TMF hub/listener event notification pattern. Systems can subscribe to catalog change events to stay synchronised.

Key Catalog Events

API	Event	When Fired
TMF620	ProductOfferingCreateEvent	A new product offering is created
TMF620	ProductOfferingStateChangeEvent	An offering transitions lifecycle state (e.g., Active to Retired)
TMF620	ProductOfferingAttributeValueChangeEvent	An offering attribute is modified (e.g., price change)
TMF633	ServiceSpecificationCreateEvent	A new service spec is created
TMF633	ServiceSpecificationStateChangeEvent	A service spec transitions state
TMF634	ResourceSpecificationCreateEvent	A new resource spec is created
TMF634	ResourceSpecificationStateChangeEvent	A resource spec transitions state

Subscribing to Catalog Changes

A digital channel frontend should subscribe to ProductOfferingStateChangeEvent so it can automatically hide retired products from the storefront. Similarly, a Service Order Management system should subscribe to ServiceSpecificationStateChangeEvent so it knows when decomposition rules have changed. This avoids stale catalog data and reduces polling overhead.

Catalog API Source of Record

Catalog Entities -- Source of Record

Entity	System of Record	System of Engagement	System of Reference	Notes
Product Offerings	Product Catalog (TMF620)	CPQ / Channel Apps	Product Catalog	Commercial catalog -- what can be sold
Product Specifications	Product Catalog (TMF620)	Product Design Tool	Product Catalog	Product structure definitions
Service Specifications (CFS/RFS)	Service Catalog (TMF633)	Service Design Tool	Service Catalog	Service blueprints and decomposition rules
Resource Specifications	Resource Catalog (TMF634)	Network Design Tool	Resource Catalog	Resource type definitions
Pricing	Product Catalog (TMF620)	CPQ / Pricing Engine	—	Pricing is always at the product offering level

Catalog Governance

Advanced

Catalog Governance Model

Catalog governance defines who can create, modify, approve, and retire catalog entries. Without governance, catalogs become cluttered with unused specs, broken references, and inconsistent naming.

A mature governance model includes: (1) Naming conventions for specifications and offerings. (2) Approval workflows for new entries (e.g., product manager approval for offerings, service architect approval for service specs). (3) Lifecycle policies (e.g., specifications must be in "In Design" for at least 2 weeks before activation). (4) Retirement rules (e.g., no active subscriptions may reference a retired spec). (5) Cross-catalog impact analysis before any retirement.

Catalog Sprawl

One of the most common problems in telco catalogs is "catalog sprawl" -- hundreds or thousands of specifications and offerings that have accumulated over years with no cleanup. This leads to duplicate entries, inconsistent naming, broken decomposition rules, and confusion across teams. Regular catalog hygiene (auditing, consolidating, and retiring stale entries) is essential.

Section 5.2 Key Takeaways

TMF620 (Product Catalog) manages what is sold: offerings, specifications, pricing, and eligibility
TMF633 (Service Catalog) manages how services are defined: CFS and RFS specifications with decomposition rules
TMF634 (Resource Catalog) manages what the network provides: physical and logical resource specifications
All three APIs follow the same pattern: Catalog > Category > Candidate > Specification
The specification/instance pattern links catalogs (design-time) to inventories (runtime)
Cross-catalog references form the decomposition chain: Product -> CFS -> RFS -> Resource
Event notifications keep downstream systems synchronised with catalog changes
Catalog governance and lifecycle management are critical to preventing sprawl and broken references