Open APIs

Dear Team,

As per my understanding, there is no restriction on keeping/defining same or different value for @type, @referredType in any of our API like 638, 639, 674 etc.

In our case there can be possibility where @type and @referredType can be same like device or gegraphicSite etc.

For e.g.: In case of place, we kept @type and @referredType same as of GeographicSite or NetworkSite... Just a basic question, do we need mandatory provide/define different values for @type and @referredType in API's.

Ideally, we can keep different value may be in some scenarios we can have same values for type and referredType..right?

Kindly let me know views/advise please.

Thanks !!!

Hi,

@type and @referredType have a very distinct meaning and should never be the same for a single reference.

Let's use the example of a relatedParty.

The default scenario is that the @type is "RelatedParty" and the @referredType is "Individual", "Organization", "PartyRole" or "Customer". This indicates the API entity that should be used to get more details. In this case @baseType is not required.

It is however possible to add more information by extending the model. In that case @baseType is "RelatedParty" @type is the name of your extended entity e.g. "RelatedPartyWithStatus" because you decided to include an extra attribute. The values of referredType stays as above.

A third option is that we have the reference entity embedded in the payload. In that case the @referredType is ommited and the @type is "Individual", "Organization". This is not a good practise for POST/PATCH operations but is a valid for GET operations where the DEPTH directive has been used.

TMF630 Part 2 provides guidance on these scenarios.

Regards

Dear Team,

As per my understanding, there is no restriction on keeping/defining same or different value for @type, @referredType in any of our API like 638, 639, 674 etc.

In our case there can be possibility where @type and @referredType can be same like device or gegraphicSite etc.

For e.g.: In case of place, we kept @type and @referredType same as of GeographicSite or NetworkSite... Just a basic question, do we need mandatory provide/define different values for @type and @referredType in API's.

Ideally, we can keep different value may be in some scenarios we can have same values for type and referredType..right?

Kindly let me know views/advise please.

Thanks !!!

Thanks @Koen Peeters for your response.

Just to clarify a little:

• All true entities in the TMF Open API model should have properties @type and @baseType - this allows entity definitions to be extended and/or polymorphism to be implemented. In v5 APIs we mandate that @type always be populated, since it is used as a discriminator in the Swagger/OAS file.
• Only certain entities in the Open API model should have property @referredType. Specifically, entities that (well) refer to other entities, such as RelatedEntity, EntityRef, and similar. In these entities @referredType must always be populated, with the type of the entity being referred to.

To give a concrete example, let's suppose that we implemented Broadband as a subclass of Product, and we also created a BroadbandRef as a subclass of ProductRef.

• Broadband payloads would have @type: Broadband and @baseType: Product
• BroadbandRef payloads would have @referredType: Broadband, @type: BroadbandRef and @baseType: ProductRef

Hope it helps

Hi,

@type and @referredType have a very distinct meaning and should never be the same for a single reference.

Let's use the example of a relatedParty.

The default scenario is that the @type is "RelatedParty" and the @referredType is "Individual", "Organization", "PartyRole" or "Customer". This indicates the API entity that should be used to get more details. In this case @baseType is not required.

It is however possible to add more information by extending the model. In that case @baseType is "RelatedParty" @type is the name of your extended entity e.g. "RelatedPartyWithStatus" because you decided to include an extra attribute. The values of referredType stays as above.

A third option is that we have the reference entity embedded in the payload. In that case the @referredType is ommited and the @type is "Individual", "Organization". This is not a good practise for POST/PATCH operations but is a valid for GET operations where the DEPTH directive has been used.

TMF630 Part 2 provides guidance on these scenarios.

Regards

Dear Team,

As per my understanding, there is no restriction on keeping/defining same or different value for @type, @referredType in any of our API like 638, 639, 674 etc.

In our case there can be possibility where @type and @referredType can be same like device or gegraphicSite etc.

For e.g.: In case of place, we kept @type and @referredType same as of GeographicSite or NetworkSite... Just a basic question, do we need mandatory provide/define different values for @type and @referredType in API's.

Ideally, we can keep different value may be in some scenarios we can have same values for type and referredType..right?

Kindly let me know views/advise please.

Thanks !!!

Thanks @Koen Peeters and @Jonathan Goldberg for your detailed explanation and clarifications. We will consider this and try to map type and referred type value accordingly with meaningful values.

One last question, Certain consumer applications are expecting source "app id" for TMF compliant API's. Does it mandatory? because we have got feedback or input from our consumers who has implemented 638 or 639 TMF Open API they are expecting source "app id" from our application when we are sending it TMF 638 and 639 API to them. I did not find any such "app id" as mandatory in TMF compliance.

Kindly guide in this regard, if possible.

Thanks @Koen Peeters for your response.

Just to clarify a little:

• All true entities in the TMF Open API model should have properties @type and @baseType - this allows entity definitions to be extended and/or polymorphism to be implemented. In v5 APIs we mandate that @type always be populated, since it is used as a discriminator in the Swagger/OAS file.
• Only certain entities in the Open API model should have property @referredType. Specifically, entities that (well) refer to other entities, such as RelatedEntity, EntityRef, and similar. In these entities @referredType must always be populated, with the type of the entity being referred to.

To give a concrete example, let's suppose that we implemented Broadband as a subclass of Product, and we also created a BroadbandRef as a subclass of ProductRef.

• Broadband payloads would have @type: Broadband and @baseType: Product
• BroadbandRef payloads would have @referredType: Broadband, @type: BroadbandRef and @baseType: ProductRef

Hope it helps

Hi,

@type and @referredType have a very distinct meaning and should never be the same for a single reference.

Let's use the example of a relatedParty.

The default scenario is that the @type is "RelatedParty" and the @referredType is "Individual", "Organization", "PartyRole" or "Customer". This indicates the API entity that should be used to get more details. In this case @baseType is not required.

It is however possible to add more information by extending the model. In that case @baseType is "RelatedParty" @type is the name of your extended entity e.g. "RelatedPartyWithStatus" because you decided to include an extra attribute. The values of referredType stays as above.

A third option is that we have the reference entity embedded in the payload. In that case the @referredType is ommited and the @type is "Individual", "Organization". This is not a good practise for POST/PATCH operations but is a valid for GET operations where the DEPTH directive has been used.

TMF630 Part 2 provides guidance on these scenarios.

Regards

Dear Team,

As per my understanding, there is no restriction on keeping/defining same or different value for @type, @referredType in any of our API like 638, 639, 674 etc.

In our case there can be possibility where @type and @referredType can be same like device or gegraphicSite etc.

For e.g.: In case of place, we kept @type and @referredType same as of GeographicSite or NetworkSite... Just a basic question, do we need mandatory provide/define different values for @type and @referredType in API's.

Ideally, we can keep different value may be in some scenarios we can have same values for type and referredType..right?

Kindly let me know views/advise please.

Thanks !!!

Thanks @Koen Peeters and @Jonathan Goldberg for your detailed explanation and clarifications. We will consider this and try to map type and referred type value accordingly with meaningful values.

One last question, Certain consumer applications are expecting source "app id" for TMF compliant API's. Does it mandatory? because we have got feedback or input from our consumers who has implemented 638 or 639 TMF Open API they are expecting source "app id" from our application when we are sending it TMF 638 and 639 API to them. I did not find any such "app id" as mandatory in TMF compliance.

Kindly guide in this regard, if possible.

Thanks @Koen Peeters for your response.

Just to clarify a little:

• All true entities in the TMF Open API model should have properties @type and @baseType - this allows entity definitions to be extended and/or polymorphism to be implemented. In v5 APIs we mandate that @type always be populated, since it is used as a discriminator in the Swagger/OAS file.
• Only certain entities in the Open API model should have property @referredType. Specifically, entities that (well) refer to other entities, such as RelatedEntity, EntityRef, and similar. In these entities @referredType must always be populated, with the type of the entity being referred to.

To give a concrete example, let's suppose that we implemented Broadband as a subclass of Product, and we also created a BroadbandRef as a subclass of ProductRef.

• Broadband payloads would have @type: Broadband and @baseType: Product
• BroadbandRef payloads would have @referredType: Broadband, @type: BroadbandRef and @baseType: ProductRef

Hope it helps

Hi,

@type and @referredType have a very distinct meaning and should never be the same for a single reference.

Let's use the example of a relatedParty.

The default scenario is that the @type is "RelatedParty" and the @referredType is "Individual", "Organization", "PartyRole" or "Customer". This indicates the API entity that should be used to get more details. In this case @baseType is not required.

It is however possible to add more information by extending the model. In that case @baseType is "RelatedParty" @type is the name of your extended entity e.g. "RelatedPartyWithStatus" because you decided to include an extra attribute. The values of referredType stays as above.

A third option is that we have the reference entity embedded in the payload. In that case the @referredType is ommited and the @type is "Individual", "Organization". This is not a good practise for POST/PATCH operations but is a valid for GET operations where the DEPTH directive has been used.

TMF630 Part 2 provides guidance on these scenarios.

Regards

Dear Team,

As per my understanding, there is no restriction on keeping/defining same or different value for @type, @referredType in any of our API like 638, 639, 674 etc.

In our case there can be possibility where @type and @referredType can be same like device or gegraphicSite etc.

For e.g.: In case of place, we kept @type and @referredType same as of GeographicSite or NetworkSite... Just a basic question, do we need mandatory provide/define different values for @type and @referredType in API's.

Ideally, we can keep different value may be in some scenarios we can have same values for type and referredType..right?

Kindly let me know views/advise please.

Thanks !!!