Open APIs

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

We are not able to find API design guidelines 3.1, to take effect for release 18.5!
Do you have the URL ?

------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.
------------------------------

Original Message:
Sent: Jul 09, 2018 02:05
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

Unfortunately it looks as if the design guidelines were not refreshed in R18.5, apologies on behalf of the Open API team.
But the R18.5 specifications (go to the Open API table for links) include examples for complex attribute values.For example in TMF 638 Service Inventory we give an example of an IP address attribute:
    "serviceCharacteristic": [
        {
            "name": "vCPE_IP",
            "valueType": "object",
            "value": {
                "@type": "IPAddress",
                "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Service/IPAddress.schema.json",
                "address": "193.218.236.21"
            }
        }
The corresponding definition in the swagger is:
"name": {
   "type": "string",
   "description": "Name of the characteristic"
},
"valueType": {
   "type": "string",
   "description": "Data type of the value of the characteristic"
},
"value": {
   "$ref": "#/definitions/Any",
   "description": "The value of the characteristic"
},
and Any is  "Any": {},

In other words there is no strong typing for the value, since Any matches any json object. For complex types (such as IP address, or list of TNs for friends and family) the provider will likely set a type name (@type) and a schema (@schemaLocation) for the type that will allow validation. The provider could give a schema also for simple types if this aligns with its business aims.

Hope it helps

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

Original Message:
Sent: May 24, 2019 17:02
From: Benoit Le Nabec
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

We are not able to find API design guidelines 3.1, to take effect for release 18.5!
Do you have the URL ?

------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.

Original Message:
Sent: Jul 09, 2018 02:05
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

Hi  Jonathan,

I used swagger generated code based on tmf 641 spec, unfortunately Any type of object is not matching to all sorts of JSON objects.
I'm not sure if it is a configuration issue or a change in parameters that we have to make while generating code.
It would be helpful if you could share any information regarding this

Thanks

------------------------------
Zayn AS
TO BE VERIFIED
------------------------------

Original Message:
Sent: May 29, 2019 07:19
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Unfortunately it looks as if the design guidelines were not refreshed in R18.5, apologies on behalf of the Open API team.
But the R18.5 specifications (go to the Open API table for links) include examples for complex attribute values.For example in TMF 638 Service Inventory we give an example of an IP address attribute:
    "serviceCharacteristic": [
        {
            "name": "vCPE_IP",
            "valueType": "object",
            "value": {
                "@type": "IPAddress",
                "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Service/IPAddress.schema.json",
                "address": "193.218.236.21"
            }
        }
The corresponding definition in the swagger is:
"name": {
   "type": "string",
   "description": "Name of the characteristic"
},
"valueType": {
   "type": "string",
   "description": "Data type of the value of the characteristic"
},
"value": {
   "$ref": "#/definitions/Any",
   "description": "The value of the characteristic"
},
and Any is  "Any": {},

In other words there is no strong typing for the value, since Any matches any json object. For complex types (such as IP address, or list of TNs for friends and family) the provider will likely set a type name (@type) and a schema (@schemaLocation) for the type that will allow validation. The provider could give a schema also for simple types if this aligns with its business aims.

Hope it helps

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

Original Message:
Sent: May 24, 2019 17:02
From: Benoit Le Nabec
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

We are not able to find API design guidelines 3.1, to take effect for release 18.5!
Do you have the URL ?

------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.

Original Message:
Sent: Jul 09, 2018 02:05
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

Due to similar concerns raised by the membership, the Open API team decided to change direction and drop Any. Instead we are going to an abstract Characteristic class (value attribute type Any is removed), and concrete subclasses with strongly-typed value attribute (e.g. StringCharacteristic has value "type": "string", BooleanCharacteristic has value "type": "boolean").

APIs to be published in the future will include this pattern.

@Ludovic Robert might be able to give an idea as to when the Service Order and other service-related APIs will be republished.

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: Mar 18, 2020 15:54
From: Zayn AS
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Hi  Jonathan,

I used swagger generated code based on tmf 641 spec, unfortunately Any type of object is not matching to all sorts of JSON objects.
I'm not sure if it is a configuration issue or a change in parameters that we have to make while generating code.
It would be helpful if you could share any information regarding this

Thanks

------------------------------
Zayn AS
TO BE VERIFIED

Original Message:
Sent: May 29, 2019 07:19
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Unfortunately it looks as if the design guidelines were not refreshed in R18.5, apologies on behalf of the Open API team.
But the R18.5 specifications (go to the Open API table for links) include examples for complex attribute values.For example in TMF 638 Service Inventory we give an example of an IP address attribute:
    "serviceCharacteristic": [
        {
            "name": "vCPE_IP",
            "valueType": "object",
            "value": {
                "@type": "IPAddress",
                "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Service/IPAddress.schema.json",
                "address": "193.218.236.21"
            }
        }
The corresponding definition in the swagger is:
"name": {
   "type": "string",
   "description": "Name of the characteristic"
},
"valueType": {
   "type": "string",
   "description": "Data type of the value of the characteristic"
},
"value": {
   "$ref": "#/definitions/Any",
   "description": "The value of the characteristic"
},
and Any is  "Any": {},

In other words there is no strong typing for the value, since Any matches any json object. For complex types (such as IP address, or list of TNs for friends and family) the provider will likely set a type name (@type) and a schema (@schemaLocation) for the type that will allow validation. The provider could give a schema also for simple types if this aligns with its business aims.

Hope it helps

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

Original Message:
Sent: May 24, 2019 17:02
From: Benoit Le Nabec
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

We are not able to find API design guidelines 3.1, to take effect for release 18.5!
Do you have the URL ?

------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.

Original Message:
Sent: Jul 09, 2018 02:05
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------

Hi,

I don't think dropping Any is a good idea as it allows to easily store any complex structure in a characteristic.
From a technical perspective, it is also very easy to map this Any value (Object in java) into a DB column of type VARCHAR or CLOB with a JPA/Hibernate mapping  using a Jackson objectMapper able to serialize/deserialize this Object into/from a String on the fly. Using the characteristic valueType or even (as in your vCPE_IP example), the schemaLocation it is then possible to transform (still with jackson) the java Object into a "concrete" object of your choice.
With this serialization, any simple types are mapped in the correct simple java type and complex types (maps starting with "{" or lists starting with "[" in json) are also mapped painlessly...

Changing that will actually make the code, the DB data model, the JSON API requests/responses more complex to read/manage/maintain...

Best regards,
Frédéric Thise

------------------------------
Frederic Thise
Proximus SA
------------------------------

Original Message:
Sent: Mar 19, 2020 10:06
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Due to similar concerns raised by the membership, the Open API team decided to change direction and drop Any. Instead we are going to an abstract Characteristic class (value attribute type Any is removed), and concrete subclasses with strongly-typed value attribute (e.g. StringCharacteristic has value "type": "string", BooleanCharacteristic has value "type": "boolean").

APIs to be published in the future will include this pattern.

@Ludovic Robert might be able to give an idea as to when the Service Order and other service-related APIs will be republished.

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: Mar 18, 2020 15:54
From: Zayn AS
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Hi  Jonathan,

I used swagger generated code based on tmf 641 spec, unfortunately Any type of object is not matching to all sorts of JSON objects.
I'm not sure if it is a configuration issue or a change in parameters that we have to make while generating code.
It would be helpful if you could share any information regarding this

Thanks

------------------------------
Zayn AS
TO BE VERIFIED

Original Message:
Sent: May 29, 2019 07:19
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Unfortunately it looks as if the design guidelines were not refreshed in R18.5, apologies on behalf of the Open API team.
But the R18.5 specifications (go to the Open API table for links) include examples for complex attribute values.For example in TMF 638 Service Inventory we give an example of an IP address attribute:
    "serviceCharacteristic": [
        {
            "name": "vCPE_IP",
            "valueType": "object",
            "value": {
                "@type": "IPAddress",
                "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Service/IPAddress.schema.json",
                "address": "193.218.236.21"
            }
        }
The corresponding definition in the swagger is:
"name": {
   "type": "string",
   "description": "Name of the characteristic"
},
"valueType": {
   "type": "string",
   "description": "Data type of the value of the characteristic"
},
"value": {
   "$ref": "#/definitions/Any",
   "description": "The value of the characteristic"
},
and Any is  "Any": {},

In other words there is no strong typing for the value, since Any matches any json object. For complex types (such as IP address, or list of TNs for friends and family) the provider will likely set a type name (@type) and a schema (@schemaLocation) for the type that will allow validation. The provider could give a schema also for simple types if this aligns with its business aims.

Hope it helps

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

Original Message:
Sent: May 24, 2019 17:02
From: Benoit Le Nabec
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

We are not able to find API design guidelines 3.1, to take effect for release 18.5!
Do you have the URL ?

------------------------------
Benoit Le Nabec
CGI Info Systems Management Consulting Inc.

Original Message:
Sent: Jul 09, 2018 02:05
From: Jonathan Goldberg
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Regarding a characteristic with a list of values (perhaps family and friend numbers is an example), @Mariano Belaunde is working on a formalization of the Characteristic/Characteristic Value pattern, which will allow characteristics to be strongly-typed with basic types or with type Object - this is set to become part of the API design guidelines 3.1, to take effect for release 18.5. Of course there is no guarantee that all the API specs will be updated in the 18.5 timescale. Suggest you reach out to Mariano to get more details, and see how the list use case can be handled.
Regarding nested characteristics, can you give a concrete example. SID has a relationship between characteristics, but in general the API model tries to simplify where this makes sense.

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

Original Message:
Sent: Jul 07, 2018 15:16
From: Adrian Ofterdinger
Subject: TMF641: Service Ordering API: Service Chararcteristic / Value

Dear TMF641 Committers and Experts,

in the TMF641 API, a specific service has n Characteristics with one value each. My question is:

• How to work with lists of values in within one characteristic?
• How to work with nested types of characteristics

Thanks in advance

Adrian

------------------------------
Adrian Ofterdinger
Capgemini
------------------------------