Open APIs

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.

I'm no expert in location management so I will refrain from answering, I was hoping the experts share their knowledge first.

I suggest you use the search box and search for the key terms or API numbers and hopefully the title will be enough or you have to read the comments.
use TM Forum's AIVA, it does an OK job at finding relevant posts in the community.

But your questions were definitely discussed in this community.

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.

Hi Jiri,

It is good to understand the purpose and layering of the different Geographic Entities  (places).

TMF675 GeographicLocation describes places using coordinates and geometric figures (point, line, polygon, multi-point, multi-line, multi-polygon). The coordinates are often GPS based but GIS systems use many other coordinates systems from cartography. 

TMF673 GeographicAddress describe places using a hierarchical system originated from the postal services. It obviously has to cope with historic differences between countries. The GeographicAddress entity repressent the public domain part of the address and GeographicSubAddress is used for detailed addresses in the private domain. The GeographicAddress has a geographicLocation property to link it to a TMF672 entity. The GeographicSubAddress has two types indicated by the value of subAddressType

• subunit is used to describe a units e.g. appartment inside a building.
• privateStreet is used to describe building in a campus

This last type is there for your campus use case and has privateStreetName, privateStreetNumber and buildingName.

TMF675 and TMF673 both describe places with conventions that are outside the control of the CSP and provided by external sources. The CSP will however have to continuously update this information to cover changes in the outside world. This often involves a verification, enrichment and certification process to maintain data quality.

TMF674 GeographicSite is used to document places under control of the CSP: a tower site, a datacenter or a streetcabinet, ... They typically have a lifeCycle linked to processes at the CSP and has various features that can be documented: power supply, cooling, acces control, health & safety, rental, subsidies. GeographicSite are often linked to GeographicAddress, GeographicSubAddress and/or GeographicLocation.

Best practice is to use relationships only in one direction:

• GeographicLocation (coordinate based places) have no external relationships
• GeographicAddress and GeographicSubAddress can reference GeographicLocation
• GeographicSite can reference all of the above

Deviating from this best practise makes data maintenance more difficult. e.g. Postal services don't know about the CSP controlled sites.

I hope this information is useful.

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.

Hi Jiri,

It is good to understand the purpose and layering of the different Geographic Entities  (places).

TMF675 GeographicLocation describes places using coordinates and geometric figures (point, line, polygon, multi-point, multi-line, multi-polygon). The coordinates are often GPS based but GIS systems use many other coordinates systems from cartography. 

TMF673 GeographicAddress describe places using a hierarchical system originated from the postal services. It obviously has to cope with historic differences between countries. The GeographicAddress entity repressent the public domain part of the address and GeographicSubAddress is used for detailed addresses in the private domain. The GeographicAddress has a geographicLocation property to link it to a TMF672 entity. The GeographicSubAddress has two types indicated by the value of subAddressType

• subunit is used to describe a units e.g. appartment inside a building.
• privateStreet is used to describe building in a campus

This last type is there for your campus use case and has privateStreetName, privateStreetNumber and buildingName.

TMF675 and TMF673 both describe places with conventions that are outside the control of the CSP and provided by external sources. The CSP will however have to continuously update this information to cover changes in the outside world. This often involves a verification, enrichment and certification process to maintain data quality.

TMF674 GeographicSite is used to document places under control of the CSP: a tower site, a datacenter or a streetcabinet, ... They typically have a lifeCycle linked to processes at the CSP and has various features that can be documented: power supply, cooling, acces control, health & safety, rental, subsidies. GeographicSite are often linked to GeographicAddress, GeographicSubAddress and/or GeographicLocation.

Best practice is to use relationships only in one direction:

• GeographicLocation (coordinate based places) have no external relationships
• GeographicAddress and GeographicSubAddress can reference GeographicLocation
• GeographicSite can reference all of the above

Deviating from this best practise makes data maintenance more difficult. e.g. Postal services don't know about the CSP controlled sites.

I hope this information is useful.

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.

HI Koen,
Thanks for the great explanation. 674 can also be used to model the actual service locations with the lifecycle of the service location based on active asset or only passive assets linked to that service location. for e.g., an ONT installation address is Site 1 (type Service location). Splitter is Site 2 (Type = Street cabinet as per the terminology you used). OLT is site 3 (Type = Network Device).
While these sites are different, there should be a relationship between the 3. Status of Site 1 is driven by the customer orders. Site 2 and Site 3 are passive. 
relating them helps not only during Assurance but also during Service Qualification. 

@David Milham @Jonathan Goldberg TMF API 674 can be used to manage all of the above sites.So would be good to have a type or a corresponding field to distinguish the type of site. 

Hi Jiri,

It is good to understand the purpose and layering of the different Geographic Entities  (places).

TMF675 GeographicLocation describes places using coordinates and geometric figures (point, line, polygon, multi-point, multi-line, multi-polygon). The coordinates are often GPS based but GIS systems use many other coordinates systems from cartography. 

TMF673 GeographicAddress describe places using a hierarchical system originated from the postal services. It obviously has to cope with historic differences between countries. The GeographicAddress entity repressent the public domain part of the address and GeographicSubAddress is used for detailed addresses in the private domain. The GeographicAddress has a geographicLocation property to link it to a TMF672 entity. The GeographicSubAddress has two types indicated by the value of subAddressType

• subunit is used to describe a units e.g. appartment inside a building.
• privateStreet is used to describe building in a campus

This last type is there for your campus use case and has privateStreetName, privateStreetNumber and buildingName.

TMF675 and TMF673 both describe places with conventions that are outside the control of the CSP and provided by external sources. The CSP will however have to continuously update this information to cover changes in the outside world. This often involves a verification, enrichment and certification process to maintain data quality.

TMF674 GeographicSite is used to document places under control of the CSP: a tower site, a datacenter or a streetcabinet, ... They typically have a lifeCycle linked to processes at the CSP and has various features that can be documented: power supply, cooling, acces control, health & safety, rental, subsidies. GeographicSite are often linked to GeographicAddress, GeographicSubAddress and/or GeographicLocation.

Best practice is to use relationships only in one direction:

• GeographicLocation (coordinate based places) have no external relationships
• GeographicAddress and GeographicSubAddress can reference GeographicLocation
• GeographicSite can reference all of the above

Deviating from this best practise makes data maintenance more difficult. e.g. Postal services don't know about the CSP controlled sites.

I hope this information is useful.

Hello,
we are working on modeling a hospital campus, real-world example:

• there is one address of the main entrance,

• there are additional addresses inside the campus,

  • sometimes corresponding to a single building,

  • sometimes covering multiple buildings.

We have found some uncertainties between TMF Open API (TMF673/674/675) and the SID model. Could you please clarify:

1) How should multiple buildings/offices on one (shared) address be modeled?

• Our requirement: multiple GeographicSite (pavilions/wings) sharing one GeographicAddress (postal identity).

• In practice, in TMF674 GeographicSite.place[] we would refer each building:

  • to the shared GeographicAddress (postal identity), and

  • to one or more specific GeographicLocation (entrance, rooftop, etc.), where the name attribute in PlaceRef could perhaps be used to indicate the role of the location.

• Is this the recommended pattern from TMF?

2) What exactly should TMF673 Geographic Address API return in the geographicSite field/attribute (cardinality 0..1)?

• In TMF673 v5, a GeographicAddress can be linked to at most one geographicSite (0..1).

• This does not match the use case where multiple sites exist on the same address.

• What is the expected behavior of the geographicSite field in TMF673?

3) Is the 0..1 cardinality of geographicSite in TMF673 correct when compared to SID?

• In SID, the pattern "multiple Sites on one Address" arises through GeographicLocation:

  • GeographicAddress → 0..* GeographicLocation (relationship GeographicAddressLocatedAt),

  • GeographicLocation → 0..1 GeographicSite (relationship GeoSiteIsRelatedTo).
    This allows 1 address → N sites (via different Locations).

• In TMF673 v5, however, GeographicAddress has 0..1 geographicLocation. This looks inconsistent with SID – is this intentional?

• SID also defines relationship SiteDefinesLocalPlace (GeographicSite 0..1 ↔ LocalPlace 0..*). The cardinality would match the API, but the LocalPlace seems more appropriate for sub-addresses than for the main address. The main address is typically defined by local authorities.

• Is the intention of the API to return only the Site that "defines a local place", or is it meant differently?

Thank you for your guidance and best practices.