Open APIs

Hi,

I wanted to add place to productOffering in TMF 620.  I just need the place to be a business label, and not an exact address or latitude/longtitudes.
Is it mandatory that i use GeographicAddress as place when aligned to TMF620?
Can I use GeographicSite in TMF 674 instead ?

Also, if using 674, should i implement GeographicSite in swagger as extension of a base schema Place (as in GeographicAddress - TMF673)? or directly create a new schema GeographicSite as per TMF674?

Thanks,
Tina

Maybe you should provide a definition of "business label". 

I would recommend you check the examples provided by the API OAS file or API user guide. I quickly found this example:

{
	"place": [
		{
			"id": "9979",
			"href": "https://mycsp.com:8080/tmfapi/geographicAddressManagement/v5/geographicAddress/9979",
			"name": "San Francisco Bay Area",
			"@referredType": "GeographicAddress",
			"@type": "PlaceRef"
		}
	]
}

Does "San Francisco Bay Area" fit your definition of "business label"? It's clearly not a street address!

you can use polymorphism (see TMF630 for details) to specialise the entity. A place could be both a continent and specific flat in a building.

• In product catalogue, Place means "where is the product offering sold". It would be a country or more granular like a list of post codes.
• In the product inventory, Place means "where is the product is used" it will always be an address, GPS coordinates etc.

 PS: Place, location, geographic Address, site etc. TMF has created many geospatial entities  (location, addresses, coordinates, sites) or spatial entities (rack positions, floor plans) in the SID and it can be confusing!

Hi,

GeoSuite/Location Management model is a bit daunting but below is the best picture I managed to find on the subject.

So a "place" is an abstract base class - as it has an id, I can't call it a raw 'interface' - which is then extended/subclassed (polymorphically) to express a site, address or location. Then the referredType would express which API/data type that the placeId  refers to(or gives the typeOf).

{	"place": [		{			"id": "9979",			"href": "https://mycsp.com:8080/tmfapi/geographicAddressManagement/v5/geographicAddress/9979",			"name": "San Francisco Bay Area",			"@referredType": "GeographicAddress",			"@type": "PlaceRef"		}	]}

Hi all,

according to my understanding:
In TMF620 the place attribute is polymorphic – a reference (PlaceRef) may point to different types of "Place": TMF673 Geographic Address, TMF675 Geographic Location, and TMF674 Geographic Site, and even their combination, as it is an array.
Meaning: "Place defines the places where the products are sold or delivered."

1) TMF673 – Geographic Address

API versions differ significantly:

• v4 – the address requires mandatory attributes including street and street number, so it effectively represents a specific point, not a broader area.

• v5 – the requirement for street-level detail seems to be removed; an address can be provided only at the level of city, locality, country, etc.

  • Another change: in v5 GeographicAddress no longer has the name attribute (the so-called friendly name). Building or sub-location names are expressed only in the sub-address (GeographicSubAddress.buildingName, GeographicSubAddress.name).

Usage for ProductOffering: if the offering applies to an area that can be expressed as an v5 address or a set of addresses, then a reference to GeographicAddress can be used.

2) TMF675 – Geographic Location

This API is designed to describe geographic areas, from v4 using GeoJSON (point, line, polygon, multipolygon).

It is suitable for cases where a ProductOffering is limited to a region that cannot be expressed by a single address.

The GeographicLocation entity has attributes such as geometry (GeoJSON) and also name, which makes it directly suitable to represent "named areas".

3) TMF674 – Geographic Site

Primarily intended to model provider or customer places such as a campus, data center, or branch, typically sites related to a technology, in my opinion.

It contains attributes like code, description, and relationships to address or geographic location – but does not have its own name field.

It could also be used more flexibly, for example to denote a sales region; categorization of sites is available using siteCategory.

Conclusion – how to handle name in a place reference

In TMF620, a ProductOffering uses PlaceRef to hold references. Each reference may contain a name.

• If the target entity (GeographicAddress v5 or GeographicSite) has no name of its own, then PlaceRef.name can be used as a business label – either entered by the user or generated by the product catalog from attributes of the referenced entity (e.g. city + buildingName, or site code + description).

• If the target entity does have a name (GeographicLocation), that value should normally be copied into PlaceRef.name. Using a different label could be confusing.

{	"place": [		{			"id": "9979",			"href": "https://mycsp.com:8080/tmfapi/geographicAddressManagement/v5/geographicAddress/9979",			"name": "San Francisco Bay Area",			"@referredType": "GeographicAddress",			"@type": "PlaceRef"		}	]}