Open APIs

I am involved in planning an implementation of TMF639 Resource Inventory Management, and have spotted some inconsistencies in the implementation of Place between the PDF and the Swagger.

The PDF defines that the Place is represented by an array of PlaceRef under Resource.

The Swagger that the OpenAPI Table leads to (https://github.com/tmforum-apis/TMF639_ResourceInventory) defines 'place' as a single entity, with the definition of 'Place' directly in the JSON as #/definitions/Place, not using the References.

I noticed a similar issue with another API in thread: https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?MessageKey=29ca59f3-b370-4967-bfe4-f87b6e2aa3c4&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer#bm29ca59f3-b370-4967-bfe4-f87b6e2aa3c4

I can see in several other APIs 'Place' has been refactored into 'PlaceRef'. This adds id/href, and moved "Role" from the place itself to the reference.

This lead to some other Swagger definitions under project https://github.com/tmforum/TMFAPISWAGGER/ which solve this issue for some APIs, but not TMF639 - there is a mention that place[] is an array under ResourceRef, but under Resource it's still a singular object.

As there are a number of sources I'm beginning to lose track of where there's an error and where I've misunderstood the specs, so apologies in advance for this long list of questions:

• PhysicalResource having 1 Place or many- I assume the PDF is definitive, how does one request an updated JSON?
• Use of Place v PlaceRef in Resource - is this a documentation issue, or a directive to return the full Place information when querying a Physical Resource? When doing Resource POST/PATCH (e.g. movement of resource from one place to another) it would certainly make more sense to use a reference.
• Which github project hosts the most accurate Swagger - tmforum-apis or tmforum/TMFAPISWAGGER - is it possible to get the links in Open API Table pointing to the right place?
• Is there a defined API to manage Places (I have checked the Geo Location APIs but these mention other entities)
  • The examples in some APIs suggest HREFs of the form .../genericCommon/place/...  , however in some /placeManagement/ is used. I've not been able to locate an API which manages these.
• Movement of 'role' from Place to PlaceRef. The Swagger is clear that Place.role was the role of place itself (e.g. Warehouse, Shop). Does the movement to PlaceRef change the meaning to be the role of the relationship, or is it expected a given Place always has the same role? Is the ID intended to be unique across all Place or just all Place with a particular Role.

​

------------------------------
Andrew Torrance
Solution Architect
Cerillion Technologies Limited

------------------------------

Hi Andrew
Thanks for your detailed post.

Please be aware that from Release 18.5 and on, we have been running a schemification project, in which all the Open APIs are being converted to using a single and consistent set of json schemas for the REST resources. The swaggers and the spec files are being generated by tools, and so there will (should be) guaranteed consistency between the spec pdf and the swagger. We hope to complete this work in R19.5, although I cannot promise anything.
Resource Inventory is in the R19.5 list, and is being handled by @Thomas Braun of Deutsche Telekom. So he may well be interested in points in your post specific to Resource Inventory.
As part of the schema work, we are also introducing and formalizing patterns, such as the RefOrValue pattern - this allows a designer to refer to an existing entity (e.g. existing Place in your example) or a new entity (which may be created as part of the operation, or may simply be passed by value, depending on the actual API semantics).

And Place is an abstract base class, which could be a Geo Address, a Site, or a Location.

The Open API table should have the correct links to the swagger files, most of these are published under Apache 2.0 but some are still under RAND, hence different GitHub repositories.

Hope this helps​

------------------------------
Jonathan Goldberg
Amdocs Management Limited
------------------------------