Hi Venkat
Thanks for bring this to our attention, copying
@Thomas Braun, who is the lead for this API.
In general, the assets for all our recently published APIs are generated from a consistent JSON schema model, so there should be no inconsistency between the swagger and the user guide. And if you compare the
definition of the API in the user guide with that in the swagger, you should see no difference.
However the examples are still hand-crafted, and so it is possible that inconsistencies can arise, as you have noticed. In a recent tooling update there is now a validation of the examples against the schema/swagger, so hopefully such inconsistencies will gradually disappear.
Specifically regarding type, we had to rename all type attributes to <xxx>type, so as not to clash with the polymorphic attribute @type .
And regarding ResourceRelationship, the id and href in this entity are the id and href of the referred Resource, this is a common pattern in the Open API model.
P.S. I have requested a tooling enhancement that would actually generate example skeletons that could then be populated manually with realistic values, not sure if and when this will happen.
------------------------------
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: Jun 24, 2020 11:43
From: Venkat Bollina
Subject: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger
I am looking at TMF639 Resource Inventory Management (V4 from Pre-Production/Beta API table), and have noticed an inconsistency in the API user guide PDF and the Swagger.
I was perticularly looking at resourceRelationship entity
In the userguide (PDF), the resource model has data element named 'relationshipType' but the examples having this data element name as 'Type' see below one of example from pdf.
...
"resourceRelationship": [
{
"type": "contains",
"resource": {
"id": "44",
"href": " http://server:port/resourceInventoryManagement/resource/44"
}
}
]
...
When i look into the Swagger (https://github.com/tmforum-apis/TMF639_ResourceInventory/commit/1e7d8ab815854fc2f7862ebd3cf92cb87f945e76), the definition for resourceRelationship looks like below:
"resourceRelationship": [
{
"id": "",
"href": "",
"relationshipType": "",
"resourceRelationshipCharacteristic": [],
"@baseType": "",
"@schemaLocation": "http://a.aaa",
"@type": ""
}
]
Notice in swagger resourceRelationship definition, I can see additional attributes id and href, The attribute name 'type' is changed to 'relationshipType', and there is no resource object attribute.
Could someone advise:
Which one is correct representation?
Is there any work currently going on to make both pdf and swagger consistent?
Thanks
------------------------------
Venkat Bollina
SSE Enterprise Telecoms
------------------------------