Open APIs

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 8 days ago
    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 6 days ago
    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
    ------------------------------