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:
Thanks in advance for any input on the subject!
------------------------------Igor TimaracTO BE VERIFIED------------------------------
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:
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.
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).