Open APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

Hi Amol
Please take a look at the published design guidelines, where the concept of extending the model is explained. We use annotations @type​ and @schemaLocation in TMF Open API resource definitions to allow a specific implementation to extend the resource.
Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
------------------------------

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group
------------------------------

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

Hi All,

Actually, this raises something that has been bothering me...  What schema structure should be expected when querying schemaLocation?

TMF630 indicates that schemaLocation should point to "yml" files.   Is this a YAML 1.2 encoding of JSON draft 7?  Or, should I be looking at something else?

For reference, I am referring to:
   - http://yaml.org/spec/1.2/spec.html 
and
   -  https://json-schema.org/specification.html 

Thanks

------------------------------
Nicholas Manson
Oracle Corporation
------------------------------

Original Message:
Sent: Nov 29, 2018 05:25
From: Stephen Harrop
Subject: Object model TMF APIs

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

Hello,

I'm also wondering about this topic: format of file pointed by @schemaLocation

I'm working with TMF633 and there, I can see directions towards Json-schema but, do we have any sample around the web for a file pointed by the @schemaLocation?
My assumption is that it could use as starting point the contents/format of swagger-file, and, any extension, should respect the specifications presented in the json-schema.org.

By checking the OpenAPI Specification, the closest I found for this definition (element that should be addressed by the @schemaLocation) is:
 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

Does it make sense?​​​

------------------------------
Marcos Donato da Silva
Ericsson Inc.
------------------------------

Original Message:
Sent: Nov 30, 2018 10:28
From: Nicholas Manson
Subject: Object model TMF APIs

Hi All,

Actually, this raises something that has been bothering me...  What schema structure should be expected when querying schemaLocation?

TMF630 indicates that schemaLocation should point to "yml" files.   Is this a YAML 1.2 encoding of JSON draft 7?  Or, should I be looking at something else?

For reference, I am referring to:
   - http://yaml.org/spec/1.2/spec.html
and
   -  https://json-schema.org/specification.html

Thanks

------------------------------
Nicholas Manson
Oracle Corporation

Original Message:
Sent: Nov 29, 2018 05:25
From: Stephen Harrop
Subject: Object model TMF APIs

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

The file pointed to by a @schemaLocation​ should contain a schema that can be parsed by the users of the API.
Typically this would be a JSON schema, but conceivably other schemas (e.g. xsd) could be entertained.
Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message:
Sent: Dec 05, 2019 08:54
From: Marcos Donato da Silva
Subject: Object model TMF APIs

Hello,

I'm also wondering about this topic: format of file pointed by @schemaLocation

I'm working with TMF633 and there, I can see directions towards Json-schema but, do we have any sample around the web for a file pointed by the @schemaLocation?
My assumption is that it could use as starting point the contents/format of swagger-file, and, any extension, should respect the specifications presented in the json-schema.org.

By checking the OpenAPI Specification, the closest I found for this definition (element that should be addressed by the @schemaLocation) is:
 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

Does it make sense?​​​

------------------------------
Marcos Donato da Silva
Ericsson Inc.

Original Message:
Sent: Nov 30, 2018 10:28
From: Nicholas Manson
Subject: Object model TMF APIs

Hi All,

Actually, this raises something that has been bothering me...  What schema structure should be expected when querying schemaLocation?

TMF630 indicates that schemaLocation should point to "yml" files.   Is this a YAML 1.2 encoding of JSON draft 7?  Or, should I be looking at something else?

For reference, I am referring to:
   - http://yaml.org/spec/1.2/spec.html
and
   -  https://json-schema.org/specification.html

Thanks

------------------------------
Nicholas Manson
Oracle Corporation

Original Message:
Sent: Nov 29, 2018 05:25
From: Stephen Harrop
Subject: Object model TMF APIs

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

Hello,

So referring the Party management example given above, if we are using default JSON attributes given in TMF API then @type, @basetype, @schemalocation should not be used in API, is my understanding correct?


------------------------------
Leena Jain
------------------------------

Original Message:
Sent: Dec 08, 2019 03:56
From: Jonathan Goldberg
Subject: Object model TMF APIs

The file pointed to by a @schemaLocation​ should contain a schema that can be parsed by the users of the API.
Typically this would be a JSON schema, but conceivably other schemas (e.g. xsd) could be entertained.
Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Dec 05, 2019 08:54
From: Marcos Donato da Silva
Subject: Object model TMF APIs

Hello,

I'm also wondering about this topic: format of file pointed by @schemaLocation

I'm working with TMF633 and there, I can see directions towards Json-schema but, do we have any sample around the web for a file pointed by the @schemaLocation?
My assumption is that it could use as starting point the contents/format of swagger-file, and, any extension, should respect the specifications presented in the json-schema.org.

By checking the OpenAPI Specification, the closest I found for this definition (element that should be addressed by the @schemaLocation) is:
 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

Does it make sense?​​​

------------------------------
Marcos Donato da Silva
Ericsson Inc.

Original Message:
Sent: Nov 30, 2018 10:28
From: Nicholas Manson
Subject: Object model TMF APIs

Hi All,

Actually, this raises something that has been bothering me...  What schema structure should be expected when querying schemaLocation?

TMF630 indicates that schemaLocation should point to "yml" files.   Is this a YAML 1.2 encoding of JSON draft 7?  Or, should I be looking at something else?

For reference, I am referring to:
   - http://yaml.org/spec/1.2/spec.html
and
   -  https://json-schema.org/specification.html

Thanks

------------------------------
Nicholas Manson
Oracle Corporation

Original Message:
Sent: Nov 29, 2018 05:25
From: Stephen Harrop
Subject: Object model TMF APIs

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------

If the type is the original TMF Open API type then you certainly don't need @baseType or @schemaLocation.
Our examples generally populate @type​​​ in the output, so that it will be clear to the consumer what is being received.

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
------------------------------

Original Message:
Sent: Dec 13, 2019 02:01
From: Leena Jain
Subject: Object model TMF APIs

Hello,

So referring the Party management example given above, if we are using default JSON attributes given in TMF API then @type, @basetype, @schemalocation should not be used in API, is my understanding correct?


------------------------------
Leena Jain

Original Message:
Sent: Dec 08, 2019 03:56
From: Jonathan Goldberg
Subject: Object model TMF APIs

The file pointed to by a @schemaLocation​ should contain a schema that can be parsed by the users of the API.
Typically this would be a JSON schema, but conceivably other schemas (e.g. xsd) could be entertained.
Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.

Original Message:
Sent: Dec 05, 2019 08:54
From: Marcos Donato da Silva
Subject: Object model TMF APIs

Hello,

I'm also wondering about this topic: format of file pointed by @schemaLocation

I'm working with TMF633 and there, I can see directions towards Json-schema but, do we have any sample around the web for a file pointed by the @schemaLocation?
My assumption is that it could use as starting point the contents/format of swagger-file, and, any extension, should respect the specifications presented in the json-schema.org.

By checking the OpenAPI Specification, the closest I found for this definition (element that should be addressed by the @schemaLocation) is:
 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject

Does it make sense?​​​

------------------------------
Marcos Donato da Silva
Ericsson Inc.

Original Message:
Sent: Nov 30, 2018 10:28
From: Nicholas Manson
Subject: Object model TMF APIs

Hi All,

Actually, this raises something that has been bothering me...  What schema structure should be expected when querying schemaLocation?

TMF630 indicates that schemaLocation should point to "yml" files.   Is this a YAML 1.2 encoding of JSON draft 7?  Or, should I be looking at something else?

For reference, I am referring to:
   - http://yaml.org/spec/1.2/spec.html
and
   -  https://json-schema.org/specification.html

Thanks

------------------------------
Nicholas Manson
Oracle Corporation

Original Message:
Sent: Nov 29, 2018 05:25
From: Stephen Harrop
Subject: Object model TMF APIs

​Hi,

You may see (in R18.0 APIs) some mention of these three attributes in various entities across the API catalog:

• ​@baseType
• @type
• @schemaLocation

These are the basis of an extension mechanism called the "Polymorphic Pattern" and will be present in every relevant entity across TMF APIs going forward. These allow your API implementation to return extensions to the payload while remaining compliant to the core TMF specification (ie: "would still pass a formal TMF conformance check").

It is analogous to sub-classing: If you wanted to return a company-specific variation of (say) Individual called "Horse" (a type-of Individual), you can implement the Party Management API, but your GET response payload might also include:

{
    "id" : "..."
    "birthDate" : "2018-09-21T09:13:16-07:00",
    "countryOfBirth" : "USA",
    "gender" : "male"
    "@baseType" : "Individual",
    "@type" : "Horse",
    "@schemaLocation" : "http://schema.myCompany.com/Horse.schema.json",
    "horseType" : "Mustang",
    "speed" : "45",
    "lifespan" : "25"
    ...
}

This allows a consumer of the API to see that you are returning a "Horse" which is a specific type of Party:: "Individual", and has additional, specific attributes (horseType, speed, lifespan) as described in the JSON schema file pointed to by "@schemaLocation". You must still remain compliant to the mandatory attributes and relationships of the "Individual" super-class (to remain TMF compliant). If your API consumer were only expecting, or only wanted to treat the response as an Individual - they they would see a valid Individual payload (id, birthDate, gender etc), and can ignore all additional Horse-specific attributes (horseType, speed, lifespan...). If they suspect that some of your Individual responses may be describing Horses, they can look out for the (non-mandatory) "@type".

I have picked a "wacky" example so as to not get tied up in technical specifics, but you can imagine doing the same with a particular "BroadbandServiceSpecification" or "CloudProductOffering". This is a better, strongly-typed and dynamically-discoverable way of extending TMF entities than with characteristics (essentially a bag of name/value pairs with an unstated common-knowledge of "what is in the bag" between the consumer/producer).

Characteristics are not going away, but this Polymorphic Pattern will be present in every subclassable entity, in every TMF API released from this point on.

Hope that helps!

------------------------------
Stephen Harrop
Principal Enterprise Architect
Vodafone Group

Original Message:
Sent: Nov 28, 2018 15:57
From: Amol Mozarkar
Subject: Object model TMF APIs

​We are migrating our monolithing soa service over to TMF based rest services. And at most places I see limitations with the SID object model, where it doesn't have name value pair generic objects in the model to allow any additional telecom specific elements to be added into the model.
I think a blank extension object should be added to every parent data object, so the SID model becomes more scalable and extendable.

For example:
TMF666 has PartyAccount object. It doesn't have some of the telecom specific account elements like CRD, CRDDDST, BAN etc. Also this object has no name-value pair generic object like characteristic where these additional details can be passed.
So Adding a PartyAccountExtension object within PatyAccount could solve this problem without corrupting the core TMF data model. And Every Telecom company can add their specific elements if any within the extension object instead of core SID model.

Any suggestions ?

------------------------------
Amol Mozarkar
Solution Architect
Member of Global Association of Enterprise Architects (globalaea.org)
Bell Canada
------------------------------