First, I'd like to respond to your family model, which is clear and nicely illustrates the principle. However, in our case, we're talking about TMF633 (the service specification – i.e. the "family model") and TMF638 (service instances – the actual "family"). According to TMF633: "Functionally, [ServiceSpecification] acts as a template by which Services may be instantiated."
As for types of relationships, let me share my perspective. Based on modeling practices (e.g. UML), we can identify these core types:
Other relationship types would likely fall into one of the above categories.
In general, I assume that relationships between service instances in inventory should be determined by the specifications in the catalog – just as class relationships define allowed object links.
In TMF633 (and other APIs), a relationship is not a separate resource, but part of a service (specification or instance). Still, I think it could include both roles. As of now, TMF633 specifies only one role – desribed as sourceRole (i.e. the role of "this" service in the relationship). But technically, it could also be used consistently as the targetRole. If both services describe the relationship, then we have both roles covered – which is particularly necessary for general associations. The assumption is that there is no more than one relationship of the same type between the two services.
(Personally, I imagine relationships as connectors in a diagram, and the list of relationships in the API as a "view" from one end. However, this not explicitly required by the TMF specs, and relationships can be oviously implemented directly just as lists related to the service.)
In some cases, bidirectional navigability may be undesirable – e.g. for performance reasons, if one RFS is shared by many CFS instances. As a possible rule for navigability, I see this: if the catalog contains a specification of the relationship in a given direction, the inventory is expected to provide that relationship. Alternatively, visibility could be controlled via rules described by ConstraintRef – e.g. the catalog describes both directions, but the inventory returns only one, or none, according to the rule. An API client can use TMF633 to discover the existence of a relationship, and then construct a more specific query to TMF638 if needed.
I believe it would be very valuable, if TMF could further develop this use case by providing concrete examples of service models in the catalog, service orders and instantiation in the inventory. :-)
Regards
Original Message:
Sent: May 05, 2025 17:03
From: Plamen Stanoev
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Hi Jiri,
For me, if an entity "A" needs to establish relation to entity "B", it is because somehow "A" (its lifecycle, behavior, etc) will be impacted by "B" .
From "B" point of view - it does not even need to know that a relationship was established to it.
This is why, the relationship description should define the target ("B"):
- "who" "B" is, exact identification - "id", "href"
- "what" type of relationship "A" wants to establish to "B" - "relationshipType"
- "why" is this relation needed, i.e. what role "B" will play in the lifecycle of "A" - "role"
- "how" will "A" name "B" in the context of the relation - "name"
I think the issues are with "role" and "name".
"role" - for me it should describe how the target "B" impacts the source "A", i.e. what role "B" plays. As this impact is the reason "A" creates relation to "B" in first place.
If "B" does not impact "A" in any way, then "A" does not need to establish relation to "B". And if "A" impacts "B", then it would be up to "B" to create relation to "A".
"name" - you are right that the name "must be contextual – only meaningful within this specific relationship".
Which means the "name" is NOT the "B"'s real name.
For example, in the relations to my 2 sisters, the relationshipType is same (family), the role they play is same (sister), but I want to differentiate between them on the UI - this is based on the names I use for them (the id's are the ultimate differentiator, but they not that 'friendly'):
{
id=111, relationshipType=family, role=sister, name=Jen // but her real name if someone does GET /party/111 will be "Jennifer Doe"
}
{
id=222, relationshipType=family, role=sister, name=Toni // same, real name if someone does GET /party/222 will be "Antonia Doe"
}
and tomorrow, I may decide to change "Jen" to "Jennie", i.e. I can patch the relationship it to be:
{
id=111, relationshipType=family, role=sister, name=Jennie // but her real name for her as a "party" stays as "Jennifer Doe"
}
About the TMF samples - I agree that sometimes they are confusing, thus I take them with a grain of salt.
I also keep in mind these documents are written by people who (like me) are not native English speakers, so "this" or "that" ("The association role for this service specification" ) may be used improperly.
And I agree with you - whatever is decided, should be clearly defined and documented.
Regards,
Plamen
------------------------------
Plamen Stanoev
Ericsson Inc.
Original Message:
Sent: May 02, 2025 11:19
From: Jiri Smekal
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Hi Plamen,
Thank you very much for your comments. I really appreciate the discussion.
There seems to be ambiguity mainly around the name attribute. I believe this ambiguity deserves clarification, especially before role and name becomes widely used across TMF638 and TMF641. Below are some observations and concerns that I hope will help define a consistent semantic interpretation.
Reference to TMF633 Service Catalog Management API User Guide:
ServiceSpecRelationship sub-resource (shortened):
-
name: A string. Name of the related entity.
-
relationshipType: A string. Type of relationship such as dependency, substitution or exclusivity.
-
role: A string. The association role for this service specification.
Examples from TMF633
serviceSpecRelationship for Firewall:
{ "relationshipType": "dependency", "role": "dependent", "id": "5563", "href": ".../serviceSpecification/5563", "name": "Points to the Deep Packet Inspection service on which this Firewall service depends", "validFor": { "startDateTime": "...", "endDateTime": "..." }, "@referredType": "ResourceFacingServiceSpecification"}
entitySpecRelationship for Firelwall:
{ "relationshipType": "ServiceSpecTestedVia", "role": "serviceUnderTest", "id": "3331", "href": ".../serviceTestSpec/3331", "name": "FirewallFunctionalTestSpec", "validFor": { "startDateTime": "...", "endDateTime": "..." }, "@referredType": "FunctionalServiceTestSpec"}
Both ServiceSpecRelationship and EntitySpecRelationship follow a similar structure and I believe they should behave the same way semantically / same pattern.
Regarding the name attribute:
-
The documentation says: name: Name of the related entity.
-
So yes, it supports your interpretation that name refers to the target entity.
However:
-
If name refers to the target service name, then it should be returned only via GET, not included in POST/PATCH. It would not make sense to define or modify the target's name from the perspective of a relationship in the source entity.
-
If name is part of POST/PATCH, and does not change the target service name, then this field must be contextual – only meaningful within this specific relationship. That makes it equivalent to a kind of targetRole. (And in that case, the role field should logically represent the sourceRole.)
-
In the Firewall example above, the name value is:
"Points to the Deep Packet Inspection service on which this Firewall service depends"
- this clearly does not look like a service name, but more like a description of the relationship or a role.
-
On the other hand, in the entitySpecRelationship example, name is "FirewallFunctionalTestSpec", which does look like a target name (eventually target role ...) Still, I have strong POST/PATCH concerns about allowing the client to insert arbitrary names unless they are truly scoped to the relationship.
Regarding the role attribute:
-
The description "The association role for this service specification" seems to refer to the source service – the one in which the relationship is declared.
-
In the Firewall example, the Firewall depends on Deep Packet Inspection, hence: "role": "dependent".
-
The same applies to "role": "serviceUnderTest" in the entitySpecRelationship.
So I see a consistent interpretation of role as sourceRole.
Implications for TMF638 and TMF641
It seems that TMF is going to add role and name to TMF641 (service order) and TMF638 (service inventory). That makes sense - it allows for consistent instantiation of relationships according to the catalog.
I believe that all involved systems must use the role and name attributes consistently, following the same semantic definition. Then it doesn't matter whether the role refers to the source or the target, but the meaning must be the same across systems. This can work internally within a company or within a vendor's sw suite.
However, for true interoperability between ODA components from various vendors or across service providers, these attributes should have have a clearly defined and standardized semantic.
P.S. Regarding the TMF638 RelatedPlaceRef:
"name" – A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]
Yes, I've noticed this one too – and honestly, I also find it unclear. Can a physical place like my home address really have a "friendly name" that is mutually recognized by both me and the provider? Possibly – but I think it deserves a separate discussion. I'd be happy to join that conversation as well.
Looking forward to further discussion and alignment
------------------------------
Jiri Smekal
T-Mobile Czech & Slovak Telekom, a.s.
Original Message:
Sent: Apr 30, 2025 11:12
From: Plamen Stanoev
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Hi Jiri,
I have some comments on your proposed meaning of these fields.
For me, the "id", href", "role", name" are all related to the target entity.
- role - should express the role played by the target service within this relation.
If you look at "relatedParty.role" is described as "Role played by the related party".
Similar for role in GeographicSiteRelationship - "Role of the related site in the relationship."
- name - I think this is a selected name for the target. Yes, the actual name of the target can be retrieved from its id/href, but this additional call is not always needed/practical.
As TMF638 specifications mention for the RelatedPlaceRef:
"name - A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]"
Regards,
Plamen
------------------------------
Plamen Stanoev
Ericsson Inc.
Original Message:
Sent: Apr 29, 2025 06:35
From: Jiri Smekal
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Hi Dan,
Thanks a lot for raising the JIRA ticket. By the way, could I get access to it?
Regarding the missing role and name attributes, I believe both are indeed missing in the ServiceRelationship object within the TMF638 and TMF641 APIs.
The name you mentioned (serviceRelationship.service.name) seems to refer to the name of the related service instance in the inventory, not the relationship itself.
My understanding of the ServiceRelationship concept is illustrated as follows:
+-----------+ +-----------+| Service A | roleOfA <--relationship--> roleOfB | Service B |+-----------+ +-----------+
-
relationshipType: defines the type of the "connector", conceptually similar also to a stereotype in UML.
-
role: should express the role of the current service within the relationship.
- In TMF633 specification, it is not fully clear whether the
role describes the current service or the related service.
However, based on examples and modeling logic, it should represent the current service's role (i.e., roleOfA in Service A specification).
- This also implies that, if we want to capture the related service's role (Service B), we must define a reciprocal relationship in Service B's specification.
name:I see two possible interpretations of its meaning:
-
-
Name/description of the role
-
Name/description of the relationship itself
-
A name for the relationship, useful for graphical models.
-
The same value would be used at both ends specifications, in case we assume one bi-directional connector in graphics.
(Modeling relationships as a separate API resource would likely remove this ambiguity, but would also cause a significant impact on API structures ...)
Main motivation of adding role and name is to support E2E scenario:
-
define services and relationships via TMF633,
-
pass through TMF641 service orders,
-
instantiate services and their relationships into TMF638 service inventory.
Best regards,
------------------------------
Jiri Smekal
T-Mobile Czech & Slovak Telekom, a.s.
Original Message:
Sent: Apr 28, 2025 04:15
From: Dan d'Albuquerque
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Hi Jiri
A JIRA has been raised ([AP-6768] TMF641/TMF638 Service Ordering/Inventory - Missing (association) role field in serviceRelationship - TM Forum JIRA).
Note that the name field already exists in the serviceRelationship.service.name field.
Hope this helps!
------------------------------
Dan d'Albuquerque
Entronica Company LimitedDan d'Albuquerque
Entronica Company Limited
Original Message:
Sent: Apr 23, 2025 08:53
From: Jiri Smekal
Subject: Missing role and name attributes in serviceRelationship for TMF638 and TMF641
Dear community,
I'm currently working on the implementation of service modeling across the TMF Open APIs, and I've encountered an inconsistency I'd like to clarify.
In TMF633 (Service Catalog Management), the serviceSpecRelationship object allows us to specify:
- relationshipType
- role
- name
This is very helpful when defining precise relationships between service specifications and for machine processing.
However, in TMF638 (Service Inventory) and TMF641 (Service Order Management), the corresponding serviceRelationship object:
- Only includes relationshipType
- Does not support role and name
This limits our ability to clearly express the semantics of relationships between service instances.
My questions are:
- Is the absence of role and name in TMF638 and TMF641 intentional, or is this an oversight or simplification?
- Are there any recommended best practices for representing the role of each service in a runtime relationship (e.g. parent/child, component/aggregator)?
- Would TMF consider extending the model to align more closely with TMF633 for consistency?
Any insights or guidance on how to best model these relationships in the current state of the APIs would be greatly appreciated. I understand that custom schema extension is possible, but is it recommended?
Thank you in advance!
Best regards,
------------------------------
Jiri Smekal
T-Mobile Czech & Slovak Telekom, a.s.
------------------------------