Open APIs

Expand all | Collapse all

Documentation or Swagger File

  • 1.  Documentation or Swagger File

    TM Forum Member
    Posted Jan 16, 2019 04:55
    Dear Forum,

    Following the swagger file for "TMF620_Product_Catalog_Management_API_REST_Specification_R17.5.0 " document, i've realized the productOffering model included on  "GET /productOffering/{id}" interface has a list of taxes inside of productOfferingPrice but this tax list is not represented in the API specification document.
    What should i Ifollow? The documentation or the swagger file?
    I took the documentation and swagger file from this link Open API Table - TM Forum Ecosystem API Portal - TM Forum Confluence

    Thanks in advance
    Best Regards,



    ------------------------------
    António Ribeiro
    Celfocus
    ------------------------------


  • 2.  RE: Documentation or Swagger File

    Posted Jan 17, 2019 07:40
      |   view attached
    Hi António

    You can see that regular Swagger from GitHub https://github.com/tmforum-apis/TMF620_ProductCatalog is uploaded in March 2018, and "TMF620_Product_Catalog_Management_API_REST_Specification_R17.5.0"  created in January 2018. So, Swagger file is more relevant in my view.

    Document ProductOfferingPrice contains  a "Price" object, which consist of taxIncludedAmount, dutyFreeAmount, taxRate and percentage attributes (See the screenshot in attachments).

    Swagger file ProductOfferingPrice has a "tax" collection.
    "tax": {
                        "type": "array", 
                        "items": {
                            "$ref": "#/definitions/Tax"
                        }
                    }
    				
    	"Tax": {
                "type": "object", 
                "description": "An amount of money levied on the price of a Product by a legislative body.", 
                "properties": {
                    "taxAmount": {
                        "$ref": "#/definitions/Money", 
                        "description": "tax amount"
                    }, 
                    "taxCategory": {
                        "$ref": "#/definitions/Money", 
                        "description": "A categorization of the tax rate."
                    }, 
                    "taxRate": {
                        "type": "number", 
                        "format": "float", 
                        "description": "Tax rate"
                    }
                }​
    And ProductOfferingPrice has no more "Price" object.

    I think you should follow the Swagger file. Also I create Swagger version control in my project to help track changes in Swaggers.

    ------------------------------
    Artyom Valeev
    Mobile TeleSystems OJSC
    ------------------------------



  • 3.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 20, 2019 14:07
    Hi all
    We are currently going through a process of rationalization that will eliminate discrepancies between the specification document and the swagger files. Both artifacts will be generated from the same underlying set of schemas for the Open API entities, and a control file for each API that defines the operations and notifications to be supported per entity. For release 18.5 this process covers eight APIs mainly in the Service domain, but we can expect it to extend to the other APIs - including product catalog - in coming releases (19, 19.5) according to priorities to be set by the program leads.
    In addition, an enhancement was made in the SID in release 18.5 to more correctly represent taxation, this enhanced model should find its way into the Product Catalog API in the coming releases.

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



  • 4.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 22, 2019 05:47

    Hello, All

    Looking at the swagger file

    https://github.com/tmforum-apis/TMF620_ProductCatalog/blob/master/TMF620_Product_Catalog_Management.regular.swagger.json

    I can see that PriceAlteration object still contains the Price structure. PriceAlteration itself is not mentioned as sub-resource of ProductOfferingPrice. That looks incorrect.

    My guess the swagger files should be verified as well as API document.

    Regards



    ------------------------------
    Viacheslav Zimovets
    Netcracker Technology
    ------------------------------



  • 5.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 23, 2019 13:35
    Hi - some additional information that will be useful. In the previous (release 14.5) product catalog API, ProductOfferingPrice was a sub-entity, embedded within ProductOffering (and including its own sub-entities Price and PriceAlteration). In the current (release 17.5) API, a revised stand-alone ProductOfferingPrice entity was introduced, without the Price and PriceAlteration sub-entities. However so as to make the change gradual, the embedded ProductOfferingPrice was kept as well. It is possible that this has caused confusion. In any case the plan is to remove the embedded POP in release 19, as per the JIRA issue https://projects.tmforum.org/jira/browse/AP-1153.
    Hope it helps

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



  • 6.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jan 25, 2019 06:31
    Hi,
    Based on your previous answer, we must follow the productOfferingPrice as a stand-alnoe entity. Even so, i would like to ask you the following questions:
    1. how can you model the following price with loyalty points: for instance IPHONE X 300€ + 1000points
    2. How does popRelationship works? Does popRelationship is list of product offering prices?

    Thanks in advance
    Best Regards,
    António Ribeiro

    ------------------------------
    António Ribeiro
    Celfocus
    ------------------------------



  • 7.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jul 03, 2019 09:59
    Hi Jonathan,
    I checked the updated ProductOffering schema on github repo. (https://github.com/tmforum-rand/schemas/blob/candidates/Product/ProductOffering.schema.json)
    As you said, productOfferingPrice entity in ProductOffering resource model doesnt include Price and Alteration subentities anymore. But it references directly to ProductOfferingPrice entity. Not ProductOfferingPriceRef. Is there a mistake here?

    Another question, how can we model the PriceAlteration subentity on ProductOffering level? Should we extend ProdOfferPriceCharge and ProdOfferPriceAlteration entities from ComponentProdOfferPrice at ProductOfferingPrice level? (as Figure Pr.11-Types of Product Offering Prices Charges -GB922_Product_R18.0.1)
    If so, how do we model the relationship between price and alteration as before?

    ------------------------------
    Koray Akyuz
    PiA-TEAM INC.
    ------------------------------



  • 8.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jul 03, 2019 10:35
    Hi Koray
    The central schema location to which you referred tends to lag behind individual schema updates in working API GitHub repositories. If you look at https://github.com/tmforum-rand/TMF620_Product_Catalog/blob/master/schemas/Product/ProductOffering.schema.json you will see:
    "productOfferingPrice": {
    "type": "array",
    "items": {
    "$ref": "ProductOfferingPriceRef.schema.json#ProductOfferingPriceRef"
    },
    "description": "An amount, usually of money, that is asked for or allowed when a ProductOffering is bought, rented, or leased. The price is valid for a defined period of time and may not represent the actual price paid by a customer."
    },

    I need to check with the relevant team members when this merge will take place so that the central location will be updated.
    But there has been some discussion that perhaps we should allow both Reference and Embedding of POP, using a RefOrValue pattern. So it is possible that there will be another small adjustment here.
    Hope it helps

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



  • 9.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jul 03, 2019 10:35
    Addendum to my previous post - I now looked at https://github.com/tmforum-rand/schemas/blob/candidates/Product/ProductOffering.schema.json and I see that my changes were merged so indeed there is now a ref to POP.
    Apologies for clicking Send too quickly.

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



  • 10.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jul 04, 2019 06:42
    Thank you so much Jonathan. i take 404 error with your link. because of that i had found that individual schemas.

    Could you please also answer my second question?
    As you said that price side is not clear here. But you can answer according to the your opinion. if we use only priceref here,
    how can we model the PriceAlteration subentity on ProductOffering level? Should we extend ProdOfferPriceCharge and ProdOfferPriceAlteration entities from ComponentProdOfferPrice at ProductOfferingPrice level? (as Figure Pr.11-Types of Product Offering Prices Charges -GB922_Product_R18.0.1)

    If so, how do we model the relationship between price and alteration as before?

    ------------------------------
    Koray Akyuz
    PiA-TEAM INC.
    ------------------------------



  • 11.  RE: Documentation or Swagger File

    TM Forum Member
    Posted Jul 08, 2019 08:42
    It was my mistake to post a URL to a location that is not publicly accessible, I apologize.
    Regarding alteration, in the new ProductOfferingPrice model, a POP serves as both a primary price and as an alteration, no need for you to introduce new entities. If you encounter difficulties with specific business use cases, it would be good for you to share them so that the collective wisdom of the forum can make suggestions :). And of course this will help us to validate/improve the model.

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