Open APIs

 View Only
Expand all | Collapse all

TMF equivalent of our concept "ServicePoint"

  • 1.  TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 06, 2025 11:36

    We have a concept called ServicePoint in our as-is-architecture and we're trying to find the most appropriate equivalent for our TMF aligned to-be-architecture.

    A ServicePoint in our system is linked with a single geographic address, which in turn can have multiple ServicePoints.
    ServicePoints pre-exists any service. They are created ahead of time for all households in areas where we build access/metro networks.
    It is used in both feasibility check and service orders to answer the question "WHERE do you want the service delivered?"

    Can anyone offer any guidance to how this concept is modelled in TMF?
    Of course the where-question hints at using a sub type of Place, but which one (including the option to extend with a specific sub type for ServicePoint)?
    There have also been suggestions to model it as a resource, but how then to use it in SQM and SOM to answer the where-question?



    ------------------------------
    Torbjørn Søiland
    Lyse Tele AS
    ------------------------------


  • 2.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 07, 2025 03:33

    Hi Torbjørn,

    I have seen this concept being represented in multiple ways, so I do not assume to provide here the one and only answer, but what is my opinion and recommendation for a best fit with the TMF semantics.

    What you call a ServicePoint is best modelled as a GeographicSite:

    • A GeographicSite's  Where is defined by GeographicAddress / SubAddress and or GeographicLocation
    • A GeographicSite has siteCategory and siteFeature to qualify it further eg. service capabilities

    Resources bound to a ServicePoint can then be linked to GeographicSite using Resource.place relationship

    I hope that helps.

    Best regards, Iwan



    ------------------------------
    Iwan Gramatikoff
    Edelweiss Service Consulting SàRL
    ------------------------------



  • 3.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 03:52

    Hi Torbjorn, Iwan,

    Iwan is correct that your ServicePoint is best modelled as a GeographicSite. GeographicSites are places with a specific relevance for the CSP. It is where Resources can be placed.

    I would like to share the siteCategories that I modelled for an FTTH network.

    Your ServicePoint probably refer to the siteCategory BuildingEntryPoint and OpticalTerminationPoint. The naming convention is derived from a FTTH Council Guidebook.
    I hope that helps.
    Best Regards


    ------------------------------
    Koen Peeters
    Ciminko SA
    ------------------------------



  • 4.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 05:24

    Thank you both for your replies.

    GeographicSite is definitely an option. I think however we would name the siteCategory "ServicePoint", since our ServicePoint is created long before fiber actually enters the building or any optical termination is installed. Do you see any problems with that?

    Also we have had suggestions to use polymorphism and define a new place type called "ServicePoint". Is that something either of you have experience with?

    place: [
    {
    id: "xxxx-yyyyyyyy-z",
    "@referredType": "ServicePoint",
    },
    ],


    ------------------------------
    Torbjørn Søiland
    Lyse Tele AS
    ------------------------------



  • 5.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 05:34
    Edited by Iwan Gramatikoff Oct 08, 2025 05:38

    Hi ,

    If you want to define ServicePoint as a strongly-typed specialization, I would recommend against defining ServicePoint as a direct specialization of Place and would rather define ServicePoint as a specialization of GeographicSite because:

    1. Your servicePoint semantically corresponds to a GeographicSite:
      From TMF674 "This API defines a Site as a convenience class that allows to easily refer to places important to other entities, where a geographic place is the entity that can answer the question "where?", allowing to determine where things are in relation to the earth's surface, and can be represented either in a textual structured way (geographic address) or as a geometry referred to a spatial reference system (geographic location) "
    2. You can directly leverage TMF674 API and TMFC014 ODA component

    Then your sample would look like that:

    place: [
    {
    id: "xxxx-yyyyyyyy-z",
    "@baseType": "GeographicSite",
    "@referredType": "ServicePoint",
    },
    ],

    Best regards, Iwan



    ------------------------------
    Iwan Gramatikoff
    Edelweiss Service Consulting SàRL
    ------------------------------



  • 6.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 05:40
    Edited by Matthieu Hattab Oct 08, 2025 05:43

    when we implemented 645, we were advised by TM forum (I forgot his name but we had a workshop with a French Canadian on this topic) to use polymorphism for place.

    The rationale was that PlaceReforValue exist in all TMF APIs that we use and need to represent service points (product inventory, product configurator, cart, order etc)

    ------------------------------
    Kind regards,

    Matthieu Hattab
    Digital Sales Domain Architect
    Lyse Tele AS
    ------------------------------



  • 7.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 05:57
    Edited by Iwan Gramatikoff Oct 08, 2025 05:58

    Hi Matthieu,

    I am not saying something different, I am just being more specific.

    Place is an abstract object, it does not have a Place API, there is no Place endpoint.

    If you want to define ServicePoint as a managed resource, you need to build on solid available ground. Thus, the recommendation to build on the existing GeographicSite API (ServicePoint as strongly-typed extension of GeographicSite), with its existing resource model, exposed by an existing ODA Component.

    If you don't (ServicePoint as strongly-typed extension of Place), you have to rebuild everything by yourself.

    Now, it's just my opinion and recommendation. As said in my initial reply, I have seen this concept being represented in multiple ways.

    BR, Iwan



    ------------------------------
    Iwan Gramatikoff
    Edelweiss Service Consulting SàRL
    ------------------------------



  • 8.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 13, 2025 03:47

    I can't find a field called siteCategory in the user guide for GeographicSite.
    Do you mean to extend GeographicSite with a siteCategory field, or does siteCategory refer to some other concept?



    ------------------------------
    Torbjørn Søiland
    Lyse Tele AS
    ------------------------------



  • 9.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 13, 2025 04:39

    Hi Torbjørn,

    I was referring to TMF674 v5. But it appears that it is one of the v5 APIs pre-releases which have been unpublished.

    In my opinion, it is safe to build on the new v5 resource model, here is the schema copied from the v5 OAS.

    BR, Iwan

        GeographicSite:
          allOf:
            - $ref: '#/components/schemas/Place'
            - type: object
              properties:
                code:
                  type: string
                  description: 'A code that may be used for some addressing schemes eg: [ANSI T1.253-1999]'
                  example: BTS
                creationDate:
                  type: string
                  format: date-time
                  description: Date and time when the GeographicSite was created
                  example: '2024-09-23T00:00:00Z'
                description:
                  type: string
                  description: Text describing additional information regarding the site
                  example: GeographiSite for the base station BS-9283
                status:
                  type: string
                  description: >-
                    The condition of the GeographicSite, such as planned, underConstruction, cancelled,
                    active, inactive, former
                  example: planned
                relatedParty:
                  type: array
                  description: Related parties collection
                  items:
                    $ref: '#/components/schemas/RelatedPartyRefOrPartyRoleRef'
                externalIdentifier:
                  type: array
                  description: Collection of external identifiers
                  items:
                    $ref: '#/components/schemas/ExternalIdentifier'
                calendar:
                  type: array
                  description: Collection of calendar items
                  items:
                    $ref: '#/components/schemas/CalendarPeriod'
                place:
                  type: array
                  description: Collection of place objects
                  items:
                    $ref: '#/components/schemas/PlaceRefOrValue'
                siteRelationship:
                  type: array
                  description: Collection of site siteRelationships
                  items:
                    $ref: '#/components/schemas/GeographicSiteRelationship'
                siteCategory:
                  type: string
                  description: Site classification/category.
                  example: ShoppingUnit
                contactMedium:
                  type: array
                  description: Collection of contact information
                  items:
                    $ref: '#/components/schemas/ContactMedium'
                siteFeature:
                  type: array
                  description: Collection of site features
                  items:
                    $ref: '#/components/schemas/GeographicSiteFeature'


    ------------------------------
    Iwan Gramatikoff
    Edelweiss Service Consulting SàRL
    ------------------------------



  • 10.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted 30 days ago

    Interesting discussion.

    We have a use case related to this pending more work in the Wholesale Broadband project: Use Cases for Multi-Site Pre-Order and Order - Standardising Wholesale Broadband – Fibre Access (BFA) - TM Forum Confluence

    My understanding of a Service Point is that the best fit is modelling it as a logical resource, however, I believe modelling it as a Site will make our life easier as several of the relevant APIs will take place as an input.

    -------------------------------------------



  • 11.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 08, 2025 05:38

    Torbjørn,

    According to the Information Framework (SID), a PhysicalResource represents tangible assets such as cables, lines, cabinets, and termination points. You can further specialise it into subclasses like FiberTerminationPoint or CopperTerminationPoint.

    When modelling the actual internet service, you can also use LogicalResource to represent logical constructs (e.g., VLANs, IP interfaces) that sit on top of the PhysicalResource.

    This entity belongs to the Resource domain (your domain) and can be associated with:

    • LogicalResource – to describe logical aspects.

    • ResourceFacingService – for services relying on the physical connection.

    • GeographicLocation or Place – for geographic mapping.

    💡 You can find detailed guidance in the SID guide (GB922) under Resources.

    In TMF APIs, some people suggest using PlaceRefOrValue or similar spatial entities to represent service points.
    Personally, I'm not a fan of this approach. A Place is not a service point and not a resource; it represents the where (the physical geographic location). Also, a Place can host multiple service points, meaning each service point should have its own unique ID, separate from the place/site/location ID.

    For example, in TMF637, the realizingResource attribute is, in my view, a better "place" (pun not intended!) to expose the Service Point than the Place entity.


    From a strict TM Forum perspective, PlaceRefOrValue is acceptable.
    However, TMF supports polymorphism, which seems to reconcile all opinions on the topic. At Lyse, we use this approach in our TMF645 implementation:

    Lyse use that method in our TMF645 implementation:

    ("place": [ { "@referredType": "ServicePoint", "id": "{{service-point-id}}" } ],)

    In that case, the API doesn't expose any place id, it's only the service point id (the service address is provided seperately in the JSON)

    I trust @Vance Shipley may have an authoritative opinion on this topic 😉



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Digital Sales Domain Architect
    Lyse Tele AS
    ------------------------------



  • 12.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 14, 2025 03:51

    Hi Torbjorn,

    A place is a place and a service is a service. What I think you mean as a service point is an actually a role a service instance has at a point of time with a place. The TMF placeRef exposed on the service (in the places[] collection) is actually a mashup of the role (a property of the placeRef) and either ref/value of the place itself.

    If you have a graph database you might actually have (:Service)-[:ServicePoint]->(:Place), where the role is encoded into the edge (relationship), effectively in this case saying that for this service instance that place is currently acting in the servicePoint role. In property graphs the edges can also be further enriched with properties, but if you need to enrich with other relationships (and we typically do for more complex relationships like service|resource to service|resource, where we can have relationshipCharacteristic[]) then you may model the PlaceRef explicitly, and have something like (:Service) -> (:PlaceRef %{role=:servicePoint}) ->(:Place).

    Hope this helps, sometimes the json rendering actually clouds the natural relationships that exist.

    Best Regards,

    Matt

    Matt Beanland, Principal Architect, Telstra

    Creator/Maintainer at diffo-dev, https://github.com/diffo-dev



    ------------------------------
    Matt Beanland
    Telstra Corporation
    ------------------------------



  • 13.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 14, 2025 04:42
    Edited by Matthieu Hattab Oct 14, 2025 05:33

    deleted



  • 14.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 14, 2025 05:10

    Matthieu, you are not the OP here so I don't think you can be so dismissive. Clearly what you are describing is a resource, however I think a nuance here with regard to the OP is that there may yet be no resources installed or planned at the 'ServicePoint' in question, merely an answer is required to the question of whether/which services could be (easily?) provided there. At Telstra we do use the placeRef role exactly for this type of thing and it works well in our ecosystem. The role is meaningless without a connection, in this case between a feasibilityChecked service (which may actually have a negative result) and a Place, Regards Matt.



    ------------------------------
    Matt Beanland
    Telstra Corporation
    ------------------------------



  • 15.  RE: TMF equivalent of our concept "ServicePoint"

    TM Forum Member
    Posted Oct 14, 2025 05:33

    @Matt Beanland,

    I apologise if my message went through as dismissive, that was certainly not the intention. It's seems my translation to English went very wrong. I have deleted my message.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Digital Sales Domain Architect
    Lyse Tele AS
    ------------------------------