It's up to consumers and providers (the humans behind them) to negotiate transition period. TMF per se does not mandate a timescale for consumers and providers to adopt the new API version. De facto there will be a long period when both v4 and gen5 APIs will need to be supported, since not all the APIs have been published in gen5 anyway.
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 05:34
From: Boris Khatkov
Subject: Backward incompatible changes in version 5.0.0
Hi Jonathan,
I definitely agree that introduction of major version is usually triggered by some backward incompatible changes. I would also definitely cope with the new version assuming it extends or reduces (e.g. replacing old features with new ones, or removing previously deprecated features) business features, attributes, methods, etc. On the other hand - when the new version brings changes to almost the entire data model (e.g. switching to strong typing) - it is a de-facto new API.
I would like to highlight that adoption of the new version will be extremely costly not just for vendors but for consumers as well, because in the end everyone would have to switchover. Maybe for vendors it is even going to be cheaper than for consumers because let's say average number of integration scenarios built using TMF APIs is way over 150. So, upgrade path for service providers becomes very-very heavy.
Maybe we need to reconsider some changes to try to reduce the pressure? Or have some transition period.
------------------------------
Boris Khatkov
Principal Solution Architect, R&D
Netcracker Technology
Original Message:
Sent: Nov 14, 2023 03:40
From: Jonathan Goldberg
Subject: Backward incompatible changes in version 5.0.0
Interesting discussion.
As a general point, the purpose of a new major version is to allow improvements to be made that break compatibility and so cannot be introduced in minor updates. We can expect the cadence of a new TMF major version to be once every 3-4 years (judging by past experience).
It is a value judgment as to whether the cost of compatibility breaks justifies the changes. Speaking from a vendor perspective it is clearly a significant effort to adopt a new version, since we need to continue to support the previous version due to customer commitments. But there was a clear need for many of these changes (Dan listed some of them):
- strongly-typed characteristic values
- strongly-typed related party pattern
- strongly-typed contact medium
- move to OAS (swagger) 3
- better semantics for refOrValue using oneOf instead of allOf
- and more
------------------------------
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: Oct 29, 2023 22:38
From: Dan d'Albuquerque
Subject: Backward incompatible changes in version 5.0.0
As far as I understand, the existence of the v5 APIs does not result in the eradication of the v4 APIs. Even for applications that have updated to support v5, these should also serve as provider to the ealier v4. The only difference being that additional features will be available for v5 consumers of the API. It is also not necessary, from my understanding, that all systems/applications will need to be updated to v5 at the same time - this will depend on whether the new features provided by v5 are required by the DSP/NOP.
You will notice that in v5, the EntityRefOrValue pattern has been used more extensively, such that a choice can be made on whether to use embedded sub-resources or re-usable, separately managed entities.
------------------------------
Dan d'Albuquerque
Individual
Original Message:
Sent: Oct 27, 2023 14:20
From: Boris Khatkov
Subject: Backward incompatible changes in version 5.0.0
Hi Dan,
I do understand that the models can be continuously improved and made better and better. However the suggested changes don't bring a lot of benefits (the content is almost the same) but make the new API backward incompatible with the previous version. Efforts to make these changes will be immense for application serving those APIs and for consumers. I still don't see justification strong enough to do that.
------------------------------
Boris Khatkov
Lead Solution Architect, R&D
Netcracker Technology
Original Message:
Sent: Oct 25, 2023 00:16
From: Dan d'Albuquerque
Subject: Backward incompatible changes in version 5.0.0
Hi Boris
One of the key changes within v5 is to use strongly-typed characteristics, removing the v4 characteristic value of type ANY. In v5, the @type attribute (metadata) is used throughout as a discriminator in the OAS and is now mandatory in the resources and sub-resources (this provides an extra layer of validation).
For the contact medium, especially relating to the geographic address, various address fields were missing from the composition and there was no reference between the Party/PartyRole Management APIs and the Geographic Address API. This also meant that the reference to a Geographic Location (coordinates) for an address was also not supported.
Please also see the link below for an explanation of the change to use polymorphism...
Why does TMF632 Party Management have its' own address format rather than use TMF673 Geopgraphic Address Management?-
------------------------------
Dan d'Albuquerque
Individual
Original Message:
Sent: Oct 18, 2023 10:11
From: Boris Khatkov
Subject: Backward incompatible changes in version 5.0.0
Hello folks,
After a brief look at the version 5 of TMF APIs I've found a lot of changes that are backward incompatible to the model of version 4.
One of the most impactful changes is Contact Medium (from composition in version 4 to inheritance in version 5). That impacts all APIs operating with Contacts Mediums which is roughly 70% for BSS domain.
What I would like to understand is at least a justification for each and every backward incompatible change. Can we discuss that?
------------------------------
Boris Khatkov
Principal Solution Architect, R&D
Netcracker Technology
------------------------------