Open APIs

 View Only
Expand all | Collapse all

TMF641: Service Ordering API: Service Chararcteristic / Value

  • 1.  TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 07, 2018 15:16
    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
    ------------------------------


  • 2.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 09, 2018 02:06
    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
    ------------------------------



  • 3.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted May 27, 2019 08:10
    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.
    ------------------------------



  • 4.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted May 29, 2019 08:09
    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
    ------------------------------



  • 5.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    Posted Mar 19, 2020 07:49
    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
    ------------------------------



  • 6.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Mar 19, 2020 10:06
    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.
    ------------------------------



  • 7.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 31, 2020 05:09
    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
    ------------------------------



  • 8.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Aug 02, 2020 01:06
    Hi Frederic

    The plan for introducing strongly-typed characteristics includes types for Object, that would give equivalent functionality to the current Any.
    Due to concerns about compatibility, it looks like this change will only be rolled out in APIs with version 5.0, not sure when this will happen.

    For example ObjectCharacteristic looks like this:
    "properties": {
    "value": {
    "type": "object",
    "description": "Value of the characteristic"
    }
    },
    "allOf": [
    {
    "$ref": "../Common/Characteristic.schema.json#Characteristic"
    }
    ]

    ------------------------------
    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.
    ------------------------------



  • 9.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 09, 2018 02:09
    Hi Adrian,

       ServiceCharacteristic have valueType, which can be complex structure (like table or array)

    ------------------------------
    Sergey N Lukin
    ------------------------------



  • 10.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 11, 2018 17:58
    Thanks, Sergey. However, from a formal perspective there is no clear definition on that. I can put any JSON structure in value. I would prefer a formal definition of the structure....
    Adrian

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



  • 11.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Mar 19, 2020 10:30
    Hi Adrian

    Like Jonathan wrote it....we're working on this to quickly the any and instead leverage @type to select a subclass (featuring strong data type for value) . With current proposal the formal definition will be in the swagger structure. We'll come back quickly on this with Service Order API as illustration.

    Hope it helps

    Ludovic



    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 12.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted May 28, 2020 05:26
    Hi Ludovic/Jonathan, 

    Notice that the ServiceCharacteristic will be change to Abstract Characteristic, is that mean to say that we can customize to create our own Characteristic beside the ​StringCharacteristic or BooleanCharacteristic. 

    For example, IPAddressCharacteristic that extending Characteristic?



    ------------------------------
    Chio Chuan Ooi
    SingTel Optus
    ------------------------------



  • 13.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted May 29, 2020 03:59
    Hello Chio

    This is a very good question.
    For me yes you could define an IPAddressCharacteristic as a Characteric specialization and define a IPAddressCharacteristic class.
    Alternative is also to leverage valueType - in this case the @type is StringCharacteristic and the valueType = "IPaddress".
    Both could work but I do not have enough feedback to comment more.

    Hope it helps
    Ludovic


    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 14.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    Posted Dec 17, 2020 08:36

    Is there a conclusion on this topic.

    What is the right way to model the complex/arrays/subarrays within the service characteristics.

    For example, modeling: 

    name1.A.X

    name1.A.Y

    name1.B.P

    name1.B.Q 

    Thanks,Harishankar



    ------------------------------
    Hari mv
    TO BE VERIFIED
    ------------------------------



  • 15.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Dec 17, 2020 09:43

    Hello Hari

    Moving forward we plan to use  @type as a discriminator and allow to manage value datatype accordingly.

    Then the payload could be... example for a complex characteristic, a string one and an integer one:

    "characteristic": [
        {
          "name": "PartyIdentityData",
          "id": "4df5-7tt",
          "@type": "ObjectCharacteristicValue",
          "value": {
              "giventName": "Jean",
              "familyName" : "Pontus",
              "contactMedium": {
                    "emailAddress": "jean.pontus@orange.fr"
              },
          }
        },
        {
            "name": "Pxxxx",
            "id": "4xxx",
            "@type": "StringCharacteristicValue",
            "value": "blu"
            }
          {
            "name": "speed",
            "id": "1",
            "@type": "IntegerCharacteristicValue",
            "value": 17
            }
      ]
      

    Hope it helps



    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 16.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    Posted Dec 18, 2020 00:01

    Thanks Ludovic.. It helps.. 

    In your example, if there is one more email address, how will that be modelled. I have pasted couple of options below, if that is ok? I'm trying to model the 5G policy data, where each subscriber will be part of different slices and each slices will have different DNNs for example, but the name of the fields is the same in each sub-blocks, like email-address or phone.. 

    {
          "name": "PartyIdentityData",
          "id": "4df5-7tt",
          "@type": "ObjectCharacteristicValue",
          "value": {
              "giventName": "Jean",
              "familyName" : "Pontus",
              "contactMedium": {
                    "emailAddress1": "jean.pontus@orange.fr",
                    "emailAddress2": "jean.pontus@yahoo.com",
              },
          }
    {
          "name": "PartyIdentityData",
          "id": "4df5-7tt",
          "@type": "ObjectCharacteristicValue",
          "value": {
              "giventName": "Jean",
              "familyName" : "Pontus",
              "contactMedium1": {
                    "emailAddress11": "jean.pontus@orange.fr",
                    "emailAddress12": "jean.pontus@yahoo.com",
                    "phone11": "123456789"
              },
              "contactMedium2": {
                    "phone21": "987654321",
              },
          }
    }


    ------------------------------
    Hari mv
    TO BE VERIFIED
    ------------------------------



  • 17.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Dec 18, 2020 04:10

    Hello Hari

    I have probably took a wrong example and use Party information as characteristic example is not a good example and could confuse people. I should have took some example based on product/Service/resource characteristics.

    Indeed if we need to capture contact medium we'll not use characteristic but existing contact medium class.

    Now about the characteristic pattern with Object datatype - for me we can expect to have a characteristic specification described in the catalog and in this payload you instantiate it. The use of the ObjectCharacteristic allows you to describe complex structure - for example we can describe connectivity with several bandwith profile(s) and associated class of service.

    Hope it helps and again sorry for the confusion,

    Ludovic



    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 18.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Apr 11, 2021 20:58
    Hi @Ludovic Robert,

    Thanks for your response. This is indeed an interesting thread and a concern raised by the developers as well. We have recently adopted 640v4 and it not having strongly typed pattern. What is the indicative timeline of incorporating this . If there is any reference to this, please share. 

    Thanks,
    Rati​

    ------------------------------
    Rati Mehrotra
    Telstra Corporation
    ------------------------------



  • 19.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Apr 12, 2021 08:17
    Hello Rati,
    We will probably introduce this strong type characteristic value with the v5.0. It will allow to remove the 'any' datatype that we have today. Currently this is work in progress within the team in schema definition.

    Thanks,
    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 20.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 21, 2022 05:26
    G'day @Ludovic Robert, Just chasing the JIRA ticket based on your response to Rati here. Do you happen to have a JIRA ticket on this that I could use as reference internally in our organisation​​

    ------------------------------
    Prince Soundararajan
    Telstra Corporation
    ------------------------------



  • 21.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 21, 2022 07:58
    Hello Prince,
    Not sure we have a Jira for that but you can find in the team git hub (OAS_Open_API_And_Data_Model / {TMF648-quote} branch) the swagger v5.0 for the quote API and it will provided you a very good idea about the direction we are taken (this new characteristic pattern has been implemented). This is not completly validated so still internal to the team (I assume some of your Telstra colleagues could get it). 

    Hope it helps,
    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 22.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 21, 2022 17:24
    Thanks for your prompt response @Ludovic Robert, Its much appreciated​​​

    ------------------------------
    Prince Soundararajan
    Telstra Corporation
    ------------------------------



  • 23.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Oct 24, 2021 21:17
    Hi Ludovic, 
    currently we are email address as a string only, can't we make it complex type where you can potentially store an array of email address?


    ------------------------------
    Sumit Jindal
    Amdocs Management Limited
    ------------------------------



  • 24.  RE: TMF641: Service Ordering API: Service Chararcteristic / Value

    TM Forum Member
    Posted Jul 21, 2022 08:01
    Hello Sumit,

    In the v5 we introduce strong type characteristic. One of them is StringArray that will allow you to use a table of string a characteristic value. This is probably useful in your context?

        StringArrayCharacteristic:
          allOf:
            - $ref: '#/components/schemas/Characteristic'
            - type: object
              description: A characteristic which value is an array of String(s).
              properties:
                value:
                  type: array
                  items:
                    type: string​

    Hope it helps

    Ludovic



    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------