Open APIs

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------

Hi,

I agree with you that the versioning specifcation is unsufficiently clear.

A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

I suggest to change the OpenAPI specification for version creation to reflect this:

• POST /{path}/resource : create a new entity
  • Content-Type: application/json
• POST /{path}/resource/{id}: create a new version 
  • Content-Type: application/json-patch+json or application/merge-patch+json

Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

There is are more versioning requirements that have to do with the lifecycle.

• Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
• There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
  • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
  • maybe other rules need to be defined 

Regards

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------

Hi Igor and Koen

We should distinguish between revisions and versions. In gen5, we introduce a history pattern, that allows expression of a history of entity revisions. A new set of guidelines for gen5 is nearing completion, and it will include extensive coverage of the history pattern. This is completely server-managed, in principle each change or set of changes to an entity cause a revision (think file revisions in Microsoft Office, for example).

The Version field, present in many of the Open API catalog entities (product/service/resource/entity) is completely different from this. The consumer of the API operations "decides" when a new version is to be created, and uses POST with the ID to create a new version. In v4 APIs the tooling didn't really support this, and so manual intervention would have been needed in the swagger to add the ID. Hopefully this was resolved in gen5.

Koen is correct, in principle, about the interaction between entity states and versions; we didn't really addressed this in the user guide and it would probably be a useful addition. I would say that more generally we need to consider the whole area of Product Lifecycle Management (PLM) going forward in TMF620 (and similarly for the S/R/E catalogs).

Hi,

I agree with you that the versioning specifcation is unsufficiently clear.

A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

I suggest to change the OpenAPI specification for version creation to reflect this:

• POST /{path}/resource : create a new entity
  • Content-Type: application/json
• POST /{path}/resource/{id}: create a new version 
  • Content-Type: application/json-patch+json or application/merge-patch+json

Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

There is are more versioning requirements that have to do with the lifecycle.

• Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
• There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
  • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
  • maybe other rules need to be defined 

Regards

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------

Hi, TM Forum members

Relating what Jonathan explained "revision vs. versioning" and trying to match those concepts to the Notification Resource Models in both TMF620 v4 and v5 the create vs valueChange events pose me the following doubts:

• If I modify a PO characteristic value while keeping the same version this should trigguer a productOfferingAttributeValueChangeEvent while if the version is changed the event should be productOfferingCreateEvent?
• Should a catalog allow the user to modify a PO characteristic value while keeping the same version if the PO status is "Active"?
• Is the "Product Offering Attribute Value Change Event" applicable to any entity with status not in("In design";"In Test")?

Thanks in advance for any input on this.

Hi Igor and Koen

We should distinguish between revisions and versions. In gen5, we introduce a history pattern, that allows expression of a history of entity revisions. A new set of guidelines for gen5 is nearing completion, and it will include extensive coverage of the history pattern. This is completely server-managed, in principle each change or set of changes to an entity cause a revision (think file revisions in Microsoft Office, for example).

The Version field, present in many of the Open API catalog entities (product/service/resource/entity) is completely different from this. The consumer of the API operations "decides" when a new version is to be created, and uses POST with the ID to create a new version. In v4 APIs the tooling didn't really support this, and so manual intervention would have been needed in the swagger to add the ID. Hopefully this was resolved in gen5.

Koen is correct, in principle, about the interaction between entity states and versions; we didn't really addressed this in the user guide and it would probably be a useful addition. I would say that more generally we need to consider the whole area of Product Lifecycle Management (PLM) going forward in TMF620 (and similarly for the S/R/E catalogs).

Hi,

I agree with you that the versioning specifcation is unsufficiently clear.

A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

I suggest to change the OpenAPI specification for version creation to reflect this:

• POST /{path}/resource : create a new entity
  • Content-Type: application/json
• POST /{path}/resource/{id}: create a new version 
  • Content-Type: application/json-patch+json or application/merge-patch+json

Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

There is are more versioning requirements that have to do with the lifecycle.

• Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
• There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
  • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
  • maybe other rules need to be defined 

Regards

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------

Hi Gonçalo,

A revision is any change to an entity. An application that supports notifications should emit a notification for each revision. The history can therfore be seen as the sequence of notifcations.

A version is a different instance of an entity with the same id but a different version value. A version is created by an action of the user. The main difference between a version and an entity is that version have an lifecycle that is implicitly interlinked.

So to answer your questions:

• Your assumption matches mine. changing a characteristic generates a notification that basicly provides the next revision. Creating a new version should generate a ProductOfferingCreateEvent.
• Depending on the lifecycleStatus, changing a characteristic could be prohibited e.g. changes are allowed for lifecycleStatus inStudy and inDesign but not for any other  lifecycleStatus. for lifecycleStatus inTest and beyond probably only the lifecycleStatus can be changed by the user, because it starts impacting processes in other systems. That is where creating a version becomes interesting. It creates a new instance where changes can be prepared, tested before being launched in production. OAS doesn't provide a good way to model these rules, but in our Gateway product we use non TMF JSON objects to define these rules.
• All catalog entities basically use the same lifecycle with the same lifecycle transition rules. Lifecycle for other TMF entities can be different and therefore requires a different set of rules. 

I agree that interoperability can be difficult beause of the lack of guidelines around this lifecycle management. TM Forum balances between stricter implmentation rules and allowing innovation, but I believe at some moment in time a more detailed guideline will be required to improve interoperability.

Regards

Hi, TM Forum members

Relating what Jonathan explained "revision vs. versioning" and trying to match those concepts to the Notification Resource Models in both TMF620 v4 and v5 the create vs valueChange events pose me the following doubts:

• If I modify a PO characteristic value while keeping the same version this should trigguer a productOfferingAttributeValueChangeEvent while if the version is changed the event should be productOfferingCreateEvent?
• Should a catalog allow the user to modify a PO characteristic value while keeping the same version if the PO status is "Active"?
• Is the "Product Offering Attribute Value Change Event" applicable to any entity with status not in("In design";"In Test")?

Thanks in advance for any input on this.

Hi Igor and Koen

We should distinguish between revisions and versions. In gen5, we introduce a history pattern, that allows expression of a history of entity revisions. A new set of guidelines for gen5 is nearing completion, and it will include extensive coverage of the history pattern. This is completely server-managed, in principle each change or set of changes to an entity cause a revision (think file revisions in Microsoft Office, for example).

The Version field, present in many of the Open API catalog entities (product/service/resource/entity) is completely different from this. The consumer of the API operations "decides" when a new version is to be created, and uses POST with the ID to create a new version. In v4 APIs the tooling didn't really support this, and so manual intervention would have been needed in the swagger to add the ID. Hopefully this was resolved in gen5.

Koen is correct, in principle, about the interaction between entity states and versions; we didn't really addressed this in the user guide and it would probably be a useful addition. I would say that more generally we need to consider the whole area of Product Lifecycle Management (PLM) going forward in TMF620 (and similarly for the S/R/E catalogs).

Hi,

I agree with you that the versioning specifcation is unsufficiently clear.

A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

I suggest to change the OpenAPI specification for version creation to reflect this:

• POST /{path}/resource : create a new entity
  • Content-Type: application/json
• POST /{path}/resource/{id}: create a new version 
  • Content-Type: application/json-patch+json or application/merge-patch+json

Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

There is are more versioning requirements that have to do with the lifecycle.

• Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
• There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
  • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
  • maybe other rules need to be defined 

Regards

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------

We're now working on an update to the design guidelines Part 4, which deals with entity versioning. So hopefully we will be able to make some improvements and formalize the semantics of entity versioning.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Mar 01, 2024 09:11
From: Koen Peeters
Subject: TMF620 - Product Catalog Resource Versioning

Hi Gonçalo,

A revision is any change to an entity. An application that supports notifications should emit a notification for each revision. The history can therfore be seen as the sequence of notifcations.

A version is a different instance of an entity with the same id but a different version value. A version is created by an action of the user. The main difference between a version and an entity is that version have an lifecycle that is implicitly interlinked.

So to answer your questions:

• Your assumption matches mine. changing a characteristic generates a notification that basicly provides the next revision. Creating a new version should generate a ProductOfferingCreateEvent.
• Depending on the lifecycleStatus, changing a characteristic could be prohibited e.g. changes are allowed for lifecycleStatus inStudy and inDesign but not for any other  lifecycleStatus. for lifecycleStatus inTest and beyond probably only the lifecycleStatus can be changed by the user, because it starts impacting processes in other systems. That is where creating a version becomes interesting. It creates a new instance where changes can be prepared, tested before being launched in production. OAS doesn't provide a good way to model these rules, but in our Gateway product we use non TMF JSON objects to define these rules.
• All catalog entities basically use the same lifecycle with the same lifecycle transition rules. Lifecycle for other TMF entities can be different and therefore requires a different set of rules. 

I agree that interoperability can be difficult beause of the lack of guidelines around this lifecycle management. TM Forum balances between stricter implmentation rules and allowing innovation, but I believe at some moment in time a more detailed guideline will be required to improve interoperability.

Regards

------------------------------
Koen Peeters
OryxGateway FZ LLC

Original Message:
Sent: Mar 01, 2024 08:02
From: Gonçalo Furtado
Subject: TMF620 - Product Catalog Resource Versioning

Hi, TM Forum members

Relating what Jonathan explained "revision vs. versioning" and trying to match those concepts to the Notification Resource Models in both TMF620 v4 and v5 the create vs valueChange events pose me the following doubts:

• If I modify a PO characteristic value while keeping the same version this should trigguer a productOfferingAttributeValueChangeEvent while if the version is changed the event should be productOfferingCreateEvent?
• Should a catalog allow the user to modify a PO characteristic value while keeping the same version if the PO status is "Active"?
• Is the "Product Offering Attribute Value Change Event" applicable to any entity with status not in("In design";"In Test")?

Thanks in advance for any input on this.

------------------------------
Gonçalo Furtado
Celfocus

Original Message:
Sent: Nov 26, 2023 07:45
From: Jonathan Goldberg
Subject: TMF620 - Product Catalog Resource Versioning

Hi Igor and Koen

We should distinguish between revisions and versions. In gen5, we introduce a history pattern, that allows expression of a history of entity revisions. A new set of guidelines for gen5 is nearing completion, and it will include extensive coverage of the history pattern. This is completely server-managed, in principle each change or set of changes to an entity cause a revision (think file revisions in Microsoft Office, for example).

The Version field, present in many of the Open API catalog entities (product/service/resource/entity) is completely different from this. The consumer of the API operations "decides" when a new version is to be created, and uses POST with the ID to create a new version. In v4 APIs the tooling didn't really support this, and so manual intervention would have been needed in the swagger to add the ID. Hopefully this was resolved in gen5.

Koen is correct, in principle, about the interaction between entity states and versions; we didn't really addressed this in the user guide and it would probably be a useful addition. I would say that more generally we need to consider the whole area of Product Lifecycle Management (PLM) going forward in TMF620 (and similarly for the S/R/E catalogs).

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Nov 24, 2023 11:58
From: Koen Peeters
Subject: TMF620 - Product Catalog Resource Versioning

Hi,

I agree with you that the versioning specifcation is unsufficiently clear.

A version of an entity is an instance with the same id, another version number and a set of interdependencies with the other versions of the same entity.

This means that the management of the version number and interdependencies is a task for the resource server and should not be the responsability of the client. In my view an additional operation for creating a new version is required that doesn't use the regular create syntax and also doesn't require you to define the version number.

I suggest to change the OpenAPI specification for version creation to reflect this:

• POST /{path}/resource : create a new entity
  • Content-Type: application/json
• POST /{path}/resource/{id}: create a new version 
  • Content-Type: application/json-patch+json or application/merge-patch+json

Using this approach the creation of a new entity can automatically become version 1. Creating a new version will automatically set the version to the next available version.

The use of the same Content-Type as for PATCH also allows the next version to inherit the properties of the previous version.

There is are more versioning requirements that have to do with the lifecycle.

• Once a new version is created all operations that don't refer to a specific version should apply to the current version. (latest version except when that version is in a final state) (already described in TMF620v5)
• There will be restrictions to the state different versions can be in. For catalog items such as TMF620 this could mean
  • Only one version can have the "launched" status. Setting a version to "launched" will automatically change the status of any previous version with status="launched" to status="retired" without an explicit operation on this version.
  • maybe other rules need to be defined 

Regards

------------------------------
Koen Peeters
OryxGateway FZ LLC

Original Message:
Sent: Nov 22, 2023 08:26
From: Igor Timarac
Subject: TMF620 - Product Catalog Resource Versioning

Hi, TM Forum members

I have a few questions regarding the versioning of catalog resources in TMF620.

In the 4.1.0 API User Guide, under "Lifecycle Management Extensions to Catalog", there is an example of creating a new version of a catalog resource, namely a Product Offering (p.187), specifying both id and version. However, 4.1.0 Swagger models for catalog resources do not include id as a parameter for any of the *_Create payloads.

In version 5, the guide has pretty much the same examples, but the Swagger models are a bit refactored, and e.g. ProductOffering_FVO does support specifying id (via Entity_FVO/Addressable_FVO). What would be the correct approach to create new resource versions in 4.1.0? Should we assume that 4.1.0 *_Create Swagger models are incomplete in this regard and we need to add this property to these models?

Also (in version 5), when creating the very first version of a catalog resource (e.g. Product Offering v1.0), should id be:

• required in the payload, so that it needs to be specified by the invoker (like it needs to be specified when a new version of the existing resource is created);
• optional, so that it can be specified, but can be omitted as well, and an autogenerated value will be assigned to the newly created resource in that case, or
• prohibited, so that it must not be specified and an autogenerated ID value will always be assigned to the newly created resource.

Thanks in advance for any input on the subject!

------------------------------
Igor Timarac
TO BE VERIFIED
------------------------------