Open APIs

 View Only
  • 1.  TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 22, 2022 11:33
    Hi Team,

    If we want to extend the place attribute of 'POST /productOffering' to use GeographicAddress to use streetName, streetNr etc and GeoJson point of geographicLocation to use the coordinates. Is the below approach correct in updating the swagger file of TMF620?

    For achieving this we updated the $ref under place with as GeographicAddress(as $ref: '#/definitions/GeographicAddress') in both request and response objects along with adding the definitions of
    GeographicAddress from TMF673. Later we also added GeographicLocationRefOrValue, GeographicSubAddress definitions as these two objects were part of GeographicAddress.

    Now the updated place attribute in swagger looks like below. Is this correct way to use polymorphic extension? As we are implementing it for first time hence looking for feedback and suggestions.



    Also, wanted to verify the sample request of TMF620  also for using these extended place attributes -
             

    Seeking help and advice!

    ------------------------------
    Anita Rawat
    Proximus SA
    ------------------------------


  • 2.  RE: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 23, 2022 03:28
    Hi Anita

    Firstly, I'm not sure why you would need to extend the swagger. Place is by definition a GeoAddress or GeoLocation or GeoSite. But the ProductOffering has an array of PlaceRef, not Place. You would never embed a Place within a product offering when creating or updating, it would always be a reference. Only in retrieve (GET) if you used the depth directive would you expect to see the actual place (as its concrete subclass) in the output payload.

    Secondly, a product offering would almost never have an exact street address. The purpose of place is to delineate geographical areas where an offering can be sold, e.g. due to regulation or technology availability.

    Of course when a product offering is instantiated to a product (as part of a product order), an exact address may well be relevant, e.g. for shipping or installation. But this would be in TMF622 (order) or TMF637 (inventory), not in the catalog.

    Hope it helps

    ------------------------------
    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: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 23, 2022 04:07
    Hi Jonathan,

    Thanks for the explanation and highlighting that it is placeref in TMF620 not place.

    We are in parallel also trying to use 'POST /workorder' of TMF 697 - Work Order Management API. And in this also there is place with 'PlaceRefOrValue' and we followed the same approach of extending the swagger as I explained in the original post as we want to use streetName, streetNr etc and GeoJson point of geographicLocation to use the coordinates there as well. We thought of modifying the swagger here as we want to get streetName, streetNr, coordinate fields in the request and response object of WorkOrder_create.

    Could you please suggest if this is correct way in terms of TMF697 to extend/modify the swagger file in this case? 

    Thanks in advance!


    ------------------------------
    Anita Rawat
    Proximus SA
    ------------------------------



  • 4.  RE: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 23, 2022 09:45

    Hi Jonathan,

    The question on how to correctly specify "Place by value" was raised rather generically across API's ( for a product, service or resource order, for a ticket, for a work order ).

    We will try to look a 2nd time into using PlaceRef in some way but the external partner does not use our central Place management & currently does not validate the place, hence does not get us a valid reference. 

    You are absolutely correct that - by default/preference - one should always use reference ID's for a place ( a specific non pre-registered/managed X,Y position could perhaps be an exception).

    Now, if we were obliged to accept/support the full place object, what would be the proper construct?

    Do we assume we do not modify the original XXXorder swagger (only supporting the PlaceRef) but rather use  the schemaLocation & type to point to the other swagger?

    Something like

    "Place": [
    {
    "id": "site2101",
    "href": "/tmf-api/geographicAddressManagement/v4/geographicAddress/site2101",
    "streetNr": 99,
    "streetName": "King Albert-II-laan",
    "postcode": 1030,
    "city": "Brussels",
    "@baseType": "Place",
    "@schemaLocation": "https://.../TMF673-GeographicAddress-v4.0.1.swagger.json#/definitions/Place",
    "@type": "Place"
    }
    


    ------------------------------
    Peter Broucke
    Proximus SA
    ------------------------------



  • 5.  RE: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 23, 2022 12:27
    Hi,

    My two thoughts on this:
    1. Place is intended as a pure-virtual base class, so it is quite normal that you would only ever create a concrete sub-class of it. 
    2. ProductOffering has 0..* Place - so you could maybe have a collection of different representations of the same Place (a GeographicAddress and a GeoJSON 'Point')
    So maybe:
    ProductOffering.place =
    
    [
      {
        "id": "6d8e3c7a-8586", 
        "href": "https://api.company.com/tmf-api/geographicLocation/v4/geographicLocation/6d8e3c7a-8586",
        "name": "Babbage House",
        "@baseType": "Place",
        "@type": "GeoJsonPoint",
        "geoJson": {
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -1.3200236856937408,
                    51.41484889182162
                ]
            }
        }
      },
      {
        "id": "6d8e3c7a-8586", 
        "href": "https://api.company.com/tmf-api/geographicAddress/v4/geographicAddress/6d8e3c7a-8586",
        "@baseType": "Place",
        "@type": "GeographicAddress",
        "streetName": "The Connection",
        "name": "Babbage House",
        "city": "Newbury",
        ...
      }
    ]​


    ...or (another thought)...
    A TMF GeographicAddress already has an attribute "geographicLocation" which is a RelatedGeographicLocationRefOrValue, so an easier way of associating a lat/lon with its equivalent GeoAddress might be:

    ProductOffering.place =
    
      {
        "id": "6d8e3c7a-8586", 
        "href": "https://api.company.com/tmf-api/geographicAddress/v4/geographicAddress/6d8e3c7a-8586",
        "@baseType": "Place",
        "@type": "GeographicAddress",
        "streetName": "The Connection",
        "name": "Babbage House",
        "city": "Newbury",
        ...
        "geographicLocation": {
          "id": "6d8e3c7a-8586", 
          "href": "https://api.company.com/tmf-api/geographicLocation/v4/geographicLocation/6d8e3c7a-8586",
          "name": "Babbage House",
          "@baseType": "GeographicLocation",
          "@type": "GeoJsonPoint",
          "geoJson": {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -1.3200236856937408,
                51.41484889182162
              ]
            }
          }
        }
      }
    ]​


    Does that help at all?



    ------------------------------
    Steve Harrop
    Principal API/Integration Architect
    Vodafone Group
    ------------------------------



  • 6.  RE: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 24, 2022 03:17
    Hi Steve,

    Thanks for sharing the suggestion.  I have another question in context to impact on the original swagger file. If we want to opt for second way in your example what would be the change in the swagger file? In this post, I have also shown how we tried to extend GeographicAddress and GeographicLocation in the original swagger file. Is that correct way and suggestions for impact in swagger file.

    I am asking this question because if receive below request and try to validate it with the original swagger file then since it does not have GeographicAddress and  GeographicLocation objects the validations on these objects will not be done as it just will have the Place object and no indication or definition of GeographicAddress/GeographicLocation.


    ProductOffering.place =
    
      {
        "id": "6d8e3c7a-8586", 
        "href": "https://api.company.com/tmf-api/geographicAddress/v4/geographicAddress/6d8e3c7a-8586",
        "@baseType": "Place",
        "@type": "GeographicAddress",
        "streetName": "The Connection",
        "name": "Babbage House",
        "city": "Newbury",
        ...
        "geographicLocation": {
          "id": "6d8e3c7a-8586", 
          "href": "https://api.company.com/tmf-api/geographicLocation/v4/geographicLocation/6d8e3c7a-8586",
          "name": "Babbage House",
          "@baseType": "GeographicLocation",
          "@type": "GeoJsonPoint",
          "geoJson": {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -1.3200236856937408,
                51.41484889182162
              ]
            }
          }
        }
      }
    ]​​





    ------------------------------
    Anita Rawat
    Proximus SA
    ------------------------------



  • 7.  RE: TMF620 - Polymorphic extension of 'place' in TMF620, impact on original swagger.

    TM Forum Member
    Posted Jun 24, 2022 08:08
    Hi,

    Yes - I think you basically need to add all the relevant schemas into the definitions {} section of the swagger, so that they can be validated and (if you use them) code-generators can use them to create the relevant classes.

    Steve

    ------------------------------
    Steve Harrop
    Principal API/Integration Architect
    Vodafone Group
    ------------------------------