Open APIs

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

Hi Iwan,

I am currently working on FTTH addresses and agree with your suggestions:

Define GeographicSubAddress as allOf Place rather than Entity

According to SID GeographicSubAddress is indeed a Place and I agree that the model should be updated to reflect this.

add a parentGeographicAddress property to GeographicSubAddress as GeographicAddressRef 

Analogue to the best practise from Party and PartyRole: a PartyRole has engagedParty to point to the party. This property should even be mandatory in my view, you can't have a GeographicSubAddress without GeographicAddress.

Modeling the reverse relationship via an the Array of GeographicSubAddress is cumbersome. 

allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

Abvious consequence of the above.

The above change also allows a GeographicSite to link to either a GeographicAddress or a GeographicSubAddress.

We are using the TMF674 GeographicSite entity to model the FTTH status for Building or a Unit: areaPlanned, notPlanned, underConstruction, homePassed, homeConnected, ...

Also for this entity some improvements can be suggested:

Add a siteSpecification property of type GeographicSiteSpecification

This allows a classification of sites: Building, Unit (in a building), AntennaSite, Streetcabinet, ...

Best Regards

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

According to me the GeographicSubAddress is to be interpreted as an optional part of the full address & would be insufficient to describe a place on its own.
We have even more fundamental questions regarding the place object.
For us the EU Inspire model is essential in our FTTH processes. In that context a place can be a building unit or potentially the building ( also depending if you consider a single house as a building with one building unit or not ). An address being the official one, a name or a postal box address is seen as a descriptor, a way to described/identify the place.
We are looking into ways to use TMF673 to rather "point" to the building or building unit, using the address construction in TMF673.

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

Happy to see this suggestion again - I already proposed that early this year, but my Jira task AP-4215 got rejected.

Nevertheless, we still need a solution to state in which room/buidling/level a Resource or Product needs to be installed, so I suggest to adopt Iwan's proposal.

And relating a SubAddress to a GeographicSite enables to locate a building (e.g. a mobile base station somewhere "in the middle of nowhere", i.e. not having an address) at a GeographicLocation, via the PlaceRefOrValue of the Site.

According to me the GeographicSubAddress is to be interpreted as an optional part of the full address & would be insufficient to describe a place on its own.
We have even more fundamental questions regarding the place object.
For us the EU Inspire model is essential in our FTTH processes. In that context a place can be a building unit or potentially the building ( also depending if you consider a single house as a building with one building unit or not ). An address being the official one, a name or a postal box address is seen as a descriptor, a way to described/identify the place.
We are looking into ways to use TMF673 to rather "point" to the building or building unit, using the address construction in TMF673.

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

Hi Lutz,

Good to hear from you too!

I was not aware of the Jira Ticket https://projects.tmforum.org/jira/browse/AP-4215.

I had a look into it... I must say that in my opinion, there is an inconsistency between the rejection argumentation and the current resource model of TMF673. Indeed, if the approach should be to resolve the uniqueness of sub addresses at address level saying that the address id uniquely defines each sub-address, then, as a consequence:

• Address to sub-address should be 0..1 not 0..n
• Sub-address should not be addressable (having its own id / href)
• For each sub-address you need to define / represent at the interface, you have to "repeat" the representation of the (parent)address

I personally still prefer the solution as you already described it in your ticket

And I hope the API architecture team will pick up on the discussion to define a consistent solution.

BR, Iwan

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

Original Message:
Sent: Aug 18, 2023 13:08
From: Lutz Bettge
Subject: TMF673 Handling of GeographicSubAddress vs. RelatedPlace(RefOrValue)

Happy to see this suggestion again - I already proposed that early this year, but my Jira task AP-4215 got rejected.

Nevertheless, we still need a solution to state in which room/buidling/level a Resource or Product needs to be installed, so I suggest to adopt Iwan's proposal.

And relating a SubAddress to a GeographicSite enables to locate a building (e.g. a mobile base station somewhere "in the middle of nowhere", i.e. not having an address) at a GeographicLocation, via the PlaceRefOrValue of the Site.

------------------------------
Lutz Bettge
Deutsche Telekom AG

Original Message:
Sent: Aug 18, 2023 10:04
From: Peter Broucke
Subject: TMF673 Handling of GeographicSubAddress vs. RelatedPlace(RefOrValue)

According to me the GeographicSubAddress is to be interpreted as an optional part of the full address & would be insufficient to describe a place on its own.
We have even more fundamental questions regarding the place object.
For us the EU Inspire model is essential in our FTTH processes. In that context a place can be a building unit or potentially the building ( also depending if you consider a single house as a building with one building unit or not ). An address being the official one, a name or a postal box address is seen as a descriptor, a way to described/identify the place.
We are looking into ways to use TMF673 to rather "point" to the building or building unit, using the address construction in TMF673.

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

Original Message:
Sent: Aug 17, 2023 10:58
From: Iwan Gramatikoff
Subject: TMF673 Handling of GeographicSubAddress vs. RelatedPlace(RefOrValue)

Hi Community,

We are currently implementing a set of TMF open APIs for wholesales connectivity. The issue I want to address here is linked to definition of GeographicSubAddress in TMF673 and how to manage the association of an API resource to a GeographicSubAddress using RelatedPlace(RefOrValue).

Before formulating our issue more precisely and asking my question, let me state a few facts as defined in the TMF open APIs:
* GeographicAddress has 0-n GeographicSubAddress
                "geographicSubAddress": {
                    "type": "array",
                    "items": {
                      "$ref": "./GeographicSubAddress.schema.json#/definitions/GeographicSubAddress"
* GeographicAddress is defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Place.schema.json#/definitions/Place"
                }
            ]
* GeographicSubAddress is a managed entity on its own and is thus addressable, but it is NOT defined as a Place
            "allOf": [
                {
                    "$ref": "../Common/Entity.schema.json#/definitions/Entity"
                }
            ]

The use case we have is to qualify technical availability at sub-address level for FTTH. 

A Resource (TMF639) has a place property:
                "place": {
                    "type": "array",
                    "items": {
                        "$ref": "../Common/RelatedPlaceRefOrValue.schema.json#RelatedPlaceRefOrValue"
                    }

But, as GeographicSubAddress is not defined as a Place, a Resource cannot reference to a sub address

And, as GeographicSubAddress does not know its parent GeographicAddress, referring a resource to a sub-address is not sufficient - you also would need to refer to the parent address from the resource.

This, we think that a valuable change to TMF673 would be:
* Define GeographicSubAddress as allOf Place rather than Entity
* add a parentGeographicAddress property to GeographicSubAddress as GeographicSubAddressRef - this would allow to refer any API resource to either a GeographicAddress or a GeographicSubAddress using RelatedPlace(RefOrValue).

* allow a PlaceRefOrValue to be a GeographicSubAddressRef or GeographicSubAddress (extension of discriminator)

What do you think? 

Or maybe there is already a way to address the use case in the current definition that I missed?

Looking forward to your answers.

Best regards, Iwan

------------------------------
Iwan Gramatikoff
Edelweiss Service Consulting
------------------------------