Open APIs

 View Only
  • 1.  TMF620 - Product Catalog Resource Versioning

    Posted Nov 22, 2023 09:42
    Edited by Ilyas Premji Nov 23, 2023 04:23

    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

  • 2.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Nov 24, 2023 11:58


    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 


    Koen Peeters
    OryxGateway FZ LLC

  • 3.  RE: TMF620 - Product Catalog Resource Versioning

    TM Forum Member
    Posted Nov 26, 2023 07:45

    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.