Specification and Relationships

Specifications carry the actual business and technical definitions used by downstream modules. Relationships connect specifications and categories into bundles, dependencies, and compatibility rules.

This document provides business context first and then full field-level references.

Business Summary

This part of Catalog is where product and service logic is made executable for operations.

• Specification defines what can be sold/provisioned and under which lifecycle and configuration rules.
• Relationship defines how items combine in real business offers (mandatory parts, optional add-ons, one-of-many choices, auto-added items).
• Together they translate business offer design into enforceable ordering and fulfillment behavior.

Business teams use this model to:

• build reusable product templates (instead of creating ad-hoc offers repeatedly),
• control eligibility and composition rules at catalog level,
• keep commercial logic maintainable when product portfolio grows,
• ensure downstream modules (Order, Inventory, Billing, Service Orchestration) consume consistent definitions.

In short: Catalog structure (Catalog/Category) organizes the portfolio, while Specification + Relationship defines the operational business logic of the portfolio.

---

1. Business Meaning

1.1 What a Specification Represents

A specification is the canonical definition of an offerable or manageable item.

TM Forum wording:

• TMF620 ProductSpecification describes a detailed definition of a tangible/intangible object made available externally through catalog constructs.
• TMF633 ServiceSpecification describes a service template that defines characteristic structure for service instances.
• TMF634 ResourceSpecification describes a technical resource template used to define characteristics and behavior of resource entities.

Typical examples:

• mobile tariff,
• value-added service,
• logical resource,
• material item template,
• work or skill definition.

Business responsibilities:

• stable identity (code) and naming (name),
• lifecycle governance (lifecycleStatus, validity),
• taxonomy placement (category, derived catalog and catalogType),
• dynamic model extension (chars),
• instantiation behavior (instantiable, entityInstanceSpecId),
• order integration (orderLineSpecId),
• pricing linkage (currentPrice, priceList).

1.2 What Relationships Represent

Relationships define how catalog items combine or constrain each other.

Typical business patterns:

• mandatory add-on,
• optional bundle element,
• mutually exclusive options via socket,
• category-wide dependency between sets of specifications.

Relationships can connect:

• specification to specification,
• specification to category,
• category to category.

Relationship types are governed by configurable registry records.

1.3 Configuration Profile and Attribute Ownership

Specification behavior is driven by the Entities & Characteristics pattern:

• profile selection for a specification is primarily defined by the parent category (Category.entitySpecificationSpecId in the previous document),
• specification attributes are stored in Specification.chars,
• instance-specific runtime data belongs to inventory-level entities and profiles (entityInstanceSpecId).

Important distinction:

• specification attributes are shared definition attributes for all instances (for example available speed options, technical provisioning capabilities),
• instance attributes are runtime values per instance (for example IP address, serial number, activated profile).

1.4 Relationship Semantics in tSM

Relationship modeling supports two levels:

• direct endpoint relations (specification-to-specification),
• structural relations with category endpoints (specification-to-category, category-to-category).

Business effect:

• category endpoints express rules over sets of specifications,
• generated tree projections (RelationshipTree.generatedRelationship) make this explicit on the read side,
• cardinality and socket semantics enforce composition constraints.
• RelationshipTree is a calculated/denormalized Elasticsearch read model, not a primary write-side entity.

Example (category-to-category, bulk relationship):

• Category Internet.Offerings contains multiple internet products that differ mainly by speed.
• Category Internet.VAS contains value-added services.
• Instead of creating relationship records one-by-one for every internet product to every VAS, create one relationship from Internet.Offerings to Internet.VAS.
• tSM logically expands this to the same effect as explicit one-to-one links, including generated socket semantics on the read model.

1.5 Typical Modeling Flow

1. Define specification types and statuses.
2. Create specifications in target categories.
3. Define relationship types.
4. Add relationship records with cardinality and socket rules.
5. Use tree projection for read-side traversal and UI representation.

1.6 Key Field Practical Notes

Field	Practical meaning
category	Determines taxonomy placement and implicitly binds the specification to category-level profile governance.
entitySpecificationSpecId	Legacy/deprecated override; prefer category-driven profile via Category.entitySpecificationSpecId.
entityInstanceSpecId	Defines instance-level profile structure used after instantiation in inventory domains.
orderLineSpecId	Defines attributes for order-line scenarios where no persistent instance object is created.
instantiable	Business switch controlling if this definition can be instantiated operationally.
cardinalityFrom / cardinalityTo	Minimum/maximum composition constraints in bundles and dependencies.
addWithParent	Instantiation helper flag. When parent item is added (for example during product ordering), child item can be added automatically via this relationship.
socket	Exclusivity/grouping channel for compatibility and “choose one of many” patterns.
generatedRelationship	Marks read-side/generated relations derived from structural (category) rules.

1.7 TM Forum References

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

---

2. Entity Reference: Specification (Specification)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Specification primary key.
lifecycleStatus	String	Yes	No	Lifecycle status code (FK EntityCatalogSpecificationStatus.code).
code	String	Yes	No	Specification business/technical key.
name	String	Yes	No	Specification display name.
category	String	Yes	No	Owning category code (FK EntityCatalogCategory.code). Primary taxonomy and profile-governance anchor.
categoryExpand	Category	No	Yes	Expanded category object.
catalog	String	Yes	No	Catalog code derived through category path.
chars	TsmChars	No	No	Dynamic attributes for the specification.
description	String	No	No	Specification description.
instantiable	Boolean	No	No	Indicates if instances can be created from this specification.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
entitySpecificationSpecId	UUID	No	No	Deprecated profile override kept for backward compatibility. Prefer category-driven profile selection (Category.entitySpecificationSpecId).
entityInstanceSpecId	UUID	No	No	Instance profile reference used for runtime/instance-level attributes.
entityCatalogSpecificationType	String	No	No	Specification type code (FK EntityCatalogSpecificationType.code).
entityInstanceLocation1Required	EntityInstanceLocationRequired	No	No	First location requirement policy.
entityInstanceLocation2Required	EntityInstanceLocationRequired	No	No	Second location requirement policy.
currentPrice	UUID	No	Yes	Current resolved price ID (derived projection).
priceList	List<String>	No	Yes	Resolved price list references/IDs.
sortOrder	Int	No	No	Relative ordering in category.
dataTags	List<String>	No	No	Optional labels/tags.
absoluteSortOrder	Long	No	Yes	Absolute order projection in tree.
orderLineSpecId	UUID	No	No	Order-line profile for cases where ordering attributes are needed without creating a persistent instance entity.
instancePriv	List<String>	No	No	Instance privilege payload.
icon	String	No	No	UI icon metadata.
imageSmall	String	No	No	Optional image metadata.
catalogType	CatalogType	No	Yes	Derived catalog type from parent category->catalog.
processingData	ProcessingData	No	Write-only	Transient processing context used during command processing; not stored as standard business attributes.

2.1 Enum Reference: EntityInstanceLocationRequired

Value	Meaning
none	No location is required.
place	A standard locality/address-management place is required (managed in Address Management reference data).
crmAddress	A customer-specific CRM address entity is required (for example installation address). It can be linked to Address Management, but can also exist as CRM-only address text and GPS coordinates.

Practical usage:

• use place when the process must reference standardized locality objects from address management,
• use crmAddress when you need a concrete address owned by a specific customer/context (installation/service address) with optional free-text and GPS detail.

2.2 Enum Reference: SpecificationExpand

Value	Meaning
ABSOLUTE_SORT_ORDER	Expand/read absolute sort order projection.
CATEGORY	Expand owning category.
CATEGORY_CATALOG	Expand category and its catalog context.

---

3. Entity Reference: Relationships (Relationship)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Relationship primary key.
cardinalityFrom	Int	Yes	No	Minimum occurrence in relation. Used together with cardinalityTo (for example 0:1, 1:1, 0:N, 1:N).
cardinalityTo	Int	No	No	Maximum occurrence in relation. null/high value behaves as open upper bound in practical models.
to	UUID	No	No	Target specification ID (FK EntityCatalogSpecification.id).
from	UUID	No	No	Source specification ID (FK EntityCatalogSpecification.id).
categoryTo	String	No	No	Target category endpoint (code). Used for category-scoped relationship rules.
categoryFrom	String	No	No	Source category endpoint (code). Used for category-scoped relationship rules.
entitySpecificationRelationshipType	String	No	No	Relationship type code.
chars	TsmChars	No	No	Dynamic relationship metadata.
addWithParent	Boolean	No	No	Instantiation flag. If true, child can be auto-added with parent (for example installation fee auto-added with internet product).
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
socket	String	No	No	Socket/grouping key for exclusivity and composition constraints (for example choose exactly one device from a group).
data	Map<String, Any?>	No	No	Additional relationship data payload.

3.1 Practical Relationship Constraints

• Use cardinalityFrom/cardinalityTo to model mandatory vs optional bundle components.
• Use socket to model mutually exclusive variants within the same composition slot.
• Use category endpoints when the rule should apply across a whole category branch.
• Use specification endpoints when the rule must target a single explicit item.

3.2 Cardinality Variants

Common variants:

• 0:1 optional single child,
• 1:1 mandatory single child,
• 0:N optional multi-child set,
• 1:N at least one child is mandatory.

Interpretation:

• cardinalityFrom = minimum required count,
• cardinalityTo = maximum allowed count.

3.3 addWithParent Instantiation Example

Example:

• Parent product: Internet 500.
• Child product: Installation Fee.
• Relationship has addWithParent = true.

Result:

• when the parent product is instantiated/added to order, the child is automatically added through this relationship rule.

3.4 socket Selection Example (CPE Choice)

Typical use case: customer must select exactly one CPE device for internet service.

Variant A (category-based, preferred for maintainability):

• create category Internet.CPE,
• put all compatible CPE specifications into this category,
• create relationship from internet product (or product category) to Internet.CPE,
• use cardinalityFrom = 1, cardinalityTo = 1.

Result:

• one mandatory choice from the category is required,
• socket grouping is formed automatically for the generated alternatives.

Variant B (explicit relationships, higher flexibility):

• create separate relationship from internet product to each concrete CPE specification,
• set the same socket value on all those relationships,
• use cardinality rules according to business policy (typically 1:1 for mandatory single choice).

Result:

• you can control each edge individually while still forcing one-of-many selection through shared socket.

---

4. Registry Reference

4.1 Specification Relationship Type (SpecificationRelationshipType)

SpecificationRelationshipType is the relationship-level equivalent of configuration-profile governance. It allows you to classify relationship semantics and attach characteristic profiles for relationship data.

Typical type examples:

• VAS - value-added service relationship from product to optional add-ons,
• Service - link from product catalog items to service catalog items,
• HW - link from product to attached hardware/CPE.

Field	Type	Required	Read-only	Description
id	UUID	No	No	Relationship type ID.
code	String	Yes	No	Relationship type code.
name	String	Yes	No	Relationship type display name.
relationshipSpecId	UUID	No	No	Configuration profile for relationship attributes on catalog/specification-definition level. Use when relationship itself needs custom characteristics.
relationshipInstanceSpecId	UUID	No	No	Configuration profile for relationship attributes on instance level (inventory/runtime relationship instances).
description	String	No	No	Type description.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
localizationData	LocalizationData	No	No	Localization payload.

4.1.1 Catalog-level vs Instance-level Relationship Profiles

• relationshipSpecId:

  • governs characteristics of the relationship definition in catalog,
  • example: define additional fields on a VAS relationship such as commercial flags, default activation policy, display priority.

• relationshipInstanceSpecId:

  • governs characteristics of instantiated relationship objects in inventory/runtime,
  • example: instantiated link between IPTV service and a specific headend where operational parameters are stored on relationship instance level.

4.2 Specification Type Registry (EntityCatalogSpecificationType)

Field	Type	Required	Read-only	Description
id	UUID	No	No	Type record ID.
code	String	Yes	No	Technical type code.
name	String	Yes	No	Type display name.
validityFrom	Date	No	No	Validity start.
validityTo	Date	No	No	Validity end.
description	String	No	No	Type description.
localizationData	LocalizationData	No	No	Localization payload.
dataTags	List<String>	No	No	Optional labels.
config	Map<String, Any?>	No	No	Additional configuration payload.

4.3 Specification Status Registry (EntityCatalogSpecificationStatus)

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

---

5. Derived Elasticsearch View: RelationshipTree

RelationshipTree is a calculated/denormalized read model stored in Elasticsearch. It is not a primary write-side catalog entity.

Primary purpose:

• denormalize structural relationships (especially category-to-category and category-to-specification rules) into effective one-to-one relationship edges for query and traversal.

This gives the same logical result as if all explicit one-by-one relationships were created manually, while keeping authoring model compact.

Field	Type	Required	Read-only	Description
id	UUID	No	No	Relationship tree node ID.
validFrom	Date	No	No	Validity start for tree node.
validTo	Date	No	No	Validity end for tree node.
chars	TsmChars	No	No	Dynamic metadata.
parentId	List<UUID>	No	No	Parent relationship IDs.
__allParentIds	List<UUID>	No	Yes	Full parent chain projection.
__leaf	Boolean	Yes	Yes	Indicates terminal tree node.
cardinalityFrom	Int	No	No	Minimum occurrence.
cardinalityTo	Int	No	No	Maximum occurrence.
entitySpecificationRelationshipType	UUID	Yes	No	Relationship type ID reference.
entitySpecificationRelationshipTypeCode	String	Yes	No	Relationship type code.
entityFrom	UUID	Yes	No	Source entity ID.
entityTo	UUID	Yes	No	Target entity ID.
entityToIsCategory	Boolean	Yes	No	Target endpoint is a category.
entityFromIsCategory	Boolean	Yes	No	Source endpoint is a category.
catalogFrom	UUID	Yes	No	Source catalog ID.
catalogTo	UUID	Yes	No	Target catalog ID.
addWithParent	Boolean	No	No	Parent-driven add behavior.
generatedRelationship	Boolean	Yes	Yes	Indicates generated relationship node.
generatedFromRelationship	UUID	No	Yes	Parent/generated-from relationship ID.
socket	String	No	No	Socket/grouping key.

5.1 Read-Model Notes

• __allParentIds and __leaf are traversal helpers for search/UI trees.
• generatedRelationship and generatedFromRelationship provide traceability of denormalized/generated edges.
• entityFromIsCategory and entityToIsCategory preserve original endpoint semantics after denormalization.