Open APIs

 View Only
  • 1.  role in RelatedPlaceRefOrValue

    TM Forum Member
    Posted Dec 07, 2021 09:18

    Hello,

    RelatedPlaceRefOrValue pattern is used in different TMF-APIs, among many in POM & PIM APIs. This entity defines "role" as mandatory attribute. However, saying that the Place in POM/PIM can be passed in both reference and value, is the "role" required for both or on for references? And is the "role" part of relatedPlaceRef, relatedPlace, Place, PlaceRef?

    Reviewing few examples in API specifications do not look consistent in the interpretation:

     

    In TMF637-PIM:
    "relatedPlace": [ { "id": "4hhf9-rr54", "href": "https...", "name": "UNI Site for this customer", "role": "UNI Site", "@referredType": "GeographicalSite", "@schemaLocation": "https...."

     

    In TMF645-SQ:
    "place": [ { "role": "Installation Place", "@type": "GeographicAddress", "city": "San Francisco", "postcode": "94121", "streetName": "25th", "streetType": "Avenue", "streetNr": "437", "geographicAddress": [ { "levelType": "floor", "levelNumber": "3" } ] } ] },

     

    Second poin that when applying EntityRefOrValue pattern from design guideline part 2 on RelatedPlaceRefOrValue for TMF622, then:

     {

    "relatedPlaceRefOrValue": {

    "oneOf": [

    {

    "$ref": "#/components/schemas/Place"

    },

    {

    "$ref": "#/components/schemas/PlaceRef"

     

    On the other hand, looking at Place/GeoSite TMF674 API, where a site has reference to PlaceRefOrValue entity that can be passed by Ref Or Value as follows:

     {

    "PlaceRefOrValue": {

    "oneOf": [

    {

    "$ref": "#/components/schemas/Place"

    },

    {

    "$ref": "#/components/schemas/PlaceRef"

     
    I would assume the use of Place & PlaceRef should be consistent in both APIs (TMF622 & TMF674). As such, it is for me a bit unclear how to deal with "role" attribute when applying above pattern.


    Appreciate some guiding on this.

    Thanks in advance,



    ------------------------------
    Mohammad Baker
    Deutsche Telekom AG
    ------------------------------


  • 2.  RE: role in RelatedPlaceRefOrValue

    TM Forum Member
    Posted Dec 07, 2021 09:28
    Hi Mohamad
    Without going into the details of the examples, I want to share with you the design thinking behind the RelatedPlace.
    The idea is that when I refer to a Place from some other entity, it is not always clear from the context what purpose the Place is serving. Especially if the attribute is an array of Place. Hence we introduced RelatedPlace as (if you like) an Association Class, where I have the role that the place is playing. Depending on the owning entity, this could be (for example) a shipping address, a billing address, an installation location, a region where service is available, and many more; the role tells me why I am using the Place. It would not be appropriate to have role directly on Place, since the same address/location/site could be used in multiple contexts by different entities.
    Hopefully from all this, you understand why role is mandatory on RelatedPlace.
    For cases where the API designer decided that the relation to Place is unambiguous, then RelatedPlace could be skipped and there would be a direct relation via PlaceRef.
    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: role in RelatedPlaceRefOrValue

    TM Forum Member
    Posted Dec 07, 2021 09:44

    Thanks Jonathon for the clarification. This helps a lot.



    ------------------------------
    Mohammad Baker
    Deutsche Telekom AG
    ------------------------------