Open APIs

 View Only
Expand all | Collapse all

V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

  • 1.  V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    Posted Jun 24, 2020 11:44
    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
    ------------------------------


  • 2.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    TM Forum Member
    Posted Jun 25, 2020 01:57
    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.
    ------------------------------



  • 3.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    TM Forum Member
    Posted Jun 25, 2020 03:25
    Jonathan Goldberg wrote:
    | I have requested a tooling enhancement that would actually generate example skeletons that could then be populated manually with realistic values,

    That may be helpful but to attack the problem directly we should enhance the tooling to perform validation of the examples against the schemas automatically.  For example at SigScale we have incorporated the command line tool ajv-cli into our builds.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 4.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    Posted Jun 25, 2020 08:56
    Thanks Jonathan,
    With regards to dependency in example in document i am fine with that.
    With regards to ResourceRelationship, i am still not very clear, and think the Swagger specification not matching with resource model specified in pdf. Here is the resource model in the PDF:

    As we can see in the resource model, the entity resourceRelationship has got a sub class resourceRefOrValue. And resourceRelationship does not have resourceRelationshipCharacteristic subclass. Where as in swagger specification, there is no definition to reference resourceRefOrValue from resourceRelationship object, instead it has resourceRelationshipCharacteristic.
    I was actually expecting to see the resourceRelationship will have a an element 'resource' in that we can either populate either resourceRef or resource by value.

    Is my expectation is correct or Have i misunderstood here? 

    Thanks


    ------------------------------
    Venkat Bollina
    SSE Enterprise Telecoms
    ------------------------------



  • 5.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    Posted Jul 01, 2020 06:02
    Hi  @Thomas Braun, or Jonathan,
    Would you be able to advise on my previous post?
    Thanks

    ------------------------------
    Venkat Bollina
    SSE Enterprise Telecoms
    ------------------------------



  • 6.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    TM Forum Member
    Posted Jul 01, 2020 10:11
    Hi Venkat,

    it seems, that with the PDF the wrong version was published.
    In my User Guide for TMF639 the example for resourceRelationShip is:
        "resourceRelationship": [
            {
                "relationshipType": "contains",
                "resource": {
                    "id": "44",
                    "href": " http://server:port/resourceInventoryManagement/resource/44"
                }
            }
        ],

    please find the correct User Gude into the Rand Guidlab:
    https://github.com/tmforum-rand/Open_API_And_Data_Model/blob/v4.0-Sprint-2020-03/apis/TMF639_Resource_Inventory/documentation/specs-gen/TMF639_Resource_Inventory_Management_API_REST_Specification_R19.5.0.docx

    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------


    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------



  • 7.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    Posted Jul 03, 2020 08:41
    Hello Thomas,
    Would you be able to comment on swagger issue as well? as i can't see the definition for "resourceRelationship" in swagger matching to the examples/resource model in the document.

    Thanks


    ------------------------------
    Venkat Bollina
    SSE Enterprise Telecoms
    ------------------------------



  • 8.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    TM Forum Member
    Posted Jul 06, 2020 04:25
    Hi Venkat,

    into the schema/resource folder there should be a ResourceRelationship.schema.json:
    {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "ResourceRelationship.schema.json",
    "title": "ResourceRelationship",
    "definitions": {
    "ResourceRelationship": {
    "$id": "#ResourceRelationship",
    "description": "Linked resources to the one instantiate, such as [bundled] if the resource is a bundle and you want to describe the bundled resources inside this bundle; [reliesOn] if the resource needs another already owned resource to rely on (e.g. an option on an already owned mobile access resource) [targets] or [isTargeted] (depending on the way of expressing the link) for any other kind of links that may be useful",
    "type": "object",
    "required": ["relationshipType", "resource"],
    "properties": {
    "relationshipType": {
    "type": "string",
    "description": "Type of the resource relationship, such as [bundled] if the resource is a bundle and you want to describe the bundled resources inside this bundle; [reliesOn] if the resource needs another already owned resource to rely on (e.g. an option on an already owned mobile access resource) [targets] or [isTargeted] (depending on the way of expressing the link) for any other kind of links that may be useful"
    },
    "resource": {
    "$ref": "../ResourceRefOrValue.schema.json#ResourceRefOrValue"
    }
    },
    "allOf": [
    {
    "$ref": "../Common/Entity.schema.json#Entity"
    }
    ]
    }
    }
    }


    @you will see the definition of the relationshipType. This model is part for the Resource Model and of TMF639-swagger.
    Regards
    Thomas


    ------------------------------
    Thomas Braun
    Deutsche Telekom AG
    ------------------------------



  • 9.  RE: V4/ Pre-Prod - TMF639 Resource Inventory Management - Inconsistencies in API specification between PDF and Swagger

    Posted Jul 06, 2020 06:12
    Thank you Thomas,

    It is now clear to me. I can also see the latest TMF639-swagger here: https://github.com/tmforum-apis/Open_Api_And_Data_Model/blob/v4.0/apis/TMF639_Resource_Inventory/swaggers/TMF639-ResourceInventory-v4.0.0.swagger.json. I can see now in this swagger the definition of the resourceRelationship is matching with document.
    My initial confusion was because i was referring schema from "Open API Table - Pre-production (Beta)", The link here was taking me to https://github.com/tmforum-apis/TMF639_ResourceInventory the schema here seems bit old...

    Thanks for clarifying. Much appreciated.

    Thanks

    ------------------------------
    Venkat Bollina
    SSE Enterprise Telecoms
    ------------------------------