Open APIs

 View Only
Expand all | Collapse all

Characteristics Schema - Value Type

  • 1.  Characteristics Schema - Value Type

    TM Forum Member
    Posted Nov 04, 2021 16:21

    A lot of the TMF Open API (e.g TMF 632, 669, and 644) all contain the characteristic sub resource which defines a valueType (a string with the data type of the value of the characteristic) and a value which in the spec is defined as "Any"

    In terms of JSON schema there are 7 core types defined: string, number, integer, object, array, boolean and null. The JSON schema specification also provides for a number of pre-defined string formats to handle things like date, time or email address through the "format" keyword – however I don't see something similar as part of the Characteristic schema for the TMF Open APIs.

    Given that the value should be returned appropriately to the defined type, we intend to use the valueType to at least support the core JSON schema types and the predefined data types such as date-time

    Has anyone else used the characteristic value-type in this manner. 

    I cant see a issue with this but would love to hear any on the ground experience



    ------------------------------
    Lancy Mendonca
    ------------------------------


  • 2.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 25, 2022 14:06
    I also have doubts about this topic. There is no clear explanation in the specification about this. I saw some samples in documentation TMF667 like this:
    "characteristic": [ 
    { 
      "name": "pages", 
      "valueType": "integer", 
      "value": 200 
    },
    { 
      "name": "language",
      "valueType": "string", 
      "value": "en" 
    }, 
    { 
      "name": "isbn-10", 
      "valueType": "string", 
      "value": "9781492026921" 
    }]​

    In line with this, it appears that the use of core JSON types is correct. But it certainly lacks at least DateTime. Maybe @Jonathan Goldberg can help us with this topic?




    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 3.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 26, 2022 02:31
    Hi all
    The Any data type was in retrospect not the best idea. And so in v5 APIs we will be changing the characteristic pattern to have strongly-typed values, with variations for all the common types (string, integer, float, array, object, and more). But since v5 will be released only gradually, for v4 APIs you'll have to continue working with the Any data type.
    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.
    ------------------------------



  • 4.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 27, 2022 15:55
    Thanks for the answer.
    So ok, I have to stick to any data type for the value, but what can I put as valueType? Just "string" and "object" or can I use "integer", "number" (for float), "string" and "date-time"? And in that case, the value should be returned without ""? Is this the correct approach for v4 APIs? For example:
    "characteristic": [ 
    { 
      "name": "pages", 
      "valueType": "integer", 
      "value": 200 
    },
    { 
      "name": "publishingDate",
      "valueType": "date-time", 
      "value": "2022-07-04T08:00.000Z" 
    }, 
    { 
      "name": "price", 
      "valueType": "number", 
      "value": 81.12
    }]​​


    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 5.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 28, 2022 05:20
    As far as I am aware the Open API does not impose any restriction on the contents of "valueType", I guess it's your responsibility to make sure that the actual data type you used for "value" is consistent with the contents of "valueType".

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



  • 6.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 28, 2022 05:23
    Thanks a lot. That is very helpful information.

    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 7.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted May 04, 2022 07:20
    I have another question. How to use an array of values in a characteristic? Should I repeat a characteristic record with the same name (according to the specification, the name is not unique) and another id like this:
    "characteristic": [ 
    	{ 
    	  "id" : "pages-0,
    	  "name": "pages", 
              "valueType": "integer", 
              "value": 100 
    	},
    	{ 
    	  "id" : "pages-1,
    	  "name": "pages", 
              "valueType": "integer", 
              "value": 200 
    	},
    	{ 
    	  "id" : "pages-2,
    	  "name": "pages", 
              "valueType": "integer", 
              "value": 300 
    	}
     ]​

    Or I can put an array of values in the value field?

    "characteristic": [ 
    	{ 
    	  "id" : "pages-0,
    	  "name": "pages", 
              "valueType": "integer", 
              "value": [ 100, 200, 300 ]
    	}
     ]
    Thanks in a

    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 8.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted May 05, 2022 03:17
    Hi Paul

    The latter - an array of values. An array in JSON is an object, so it matches the Any syntax in v4.
    Ideally, you should try to match the schema that we will introduce in v5, for instance in your example of an integer array the schema for value will (tentatively) look similar to this:

                "properties": {
                    "value": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    }
                },
    			"allOf": [
                    {
                        "$ref": "Characteristic.schema.json#Characteristic"
                    }
                ]
    ​

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



  • 9.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted May 05, 2022 03:48
    Thank you very much for your answer.
    The approach in the v5 API version is very interesting. I am a forum user with access to some internal material, can you provide me a link to the v5 spec draft?

    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 10.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted May 08, 2022 04:04
    Hi Paul
    The materials for all the Open API design are managed in private GitHub repositories, so even if you have access to the TMF Open API collaborative project confluence pages, you will not have access to the GitHub.
    You would have to take this up with the project leads, I think.

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



  • 11.  RE: Characteristics Schema - Value Type

    Posted Jul 14, 2022 10:51

    Hi,

    Can anyone share an example of a characteristic where the valueType is an object.

    Thank You



    ------------------------------
    Jacob Bensaid
    ------------------------------



  • 12.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Jul 15, 2022 04:36
    {
    "valueType" : "object",
    "value" : {
    "value" : "Westcon",
    "previousValue" : null,
    "action" : "Add"
    },
    "name" : "SUPPLIER"

    Regards,
    Harsh

    ------------------------------
    Harsha K N
    Tech Mahindra Limited
    ------------------------------



  • 13.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Jul 15, 2022 04:46
    {
      "name": "Equipment",
      "valueType": "object",
      "value": {
         "@type": "Equipment",
         "serialNumber": "12444545544",
         "versionNumber": "1.22",
         "manufactureDate": "05-04-2017"
        },
      "@schemaLocation": "http://serverlocation:port/partyManagement/schema/Equipment.yml"
    }​


    ------------------------------
    Paul Stanek
    Suntech S.A.
    ------------------------------



  • 14.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Mar 09, 2023 12:24

    Hi all - i've a sort of related question...

    Is a valueType or "objectArray" acceptable? It seems to be documented here: http://datamodel.tmforum.org/en/latest/Common/ObjectArrayCharacteristic/ but I can't find any examples of it being used in the doco.

    Example of what I mean:

    {
       "characteristic":[
          {
             "name":"hardware",
             "valueType":"objectArray",
             "value":[
                {
                   "id":"NANOSIM",
                   "description":"NANO SIM"
                },
                {
                   "id":"IPHONE6",
                   "description":"iPhone 6"
                }
             ]
          }
       ]
    }



    ------------------------------
    Thomas O Donnell
    MDS Global Ltd
    ------------------------------



  • 15.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Mar 09, 2023 15:36

    Hi Thomas

    The value of an ObjectCharacteristic is exactly that, a JSON object, which can be basically any structure between { and }. You also have a an ObjectArrayCharacteristic, an array of JSON objects.

    The tricky part of this is that you'll presumably need to define a schema for your object or object array so that you can validate payloads. You need to consider carefully whether it might be better to define a compound ProductSpecification instead, hosting simpler characteristics.

    Good luck



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



  • 16.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Mar 10, 2023 05:53

    Thanks for replying Jonathan,

    For a little more context, our existing APIs return hardware assigned to a customer in the GET Customer request and this needs to be replicated in the TMF629 GET requests (I understand it may not exactly be best practice but it's a hard requirement). It's informative only - it will not be possible to update these values using POST or PATCH.

    I had assumed the only place this can exist is in the Characteristic sub-resource. Can I define a unique resouce called ProductSpecification in TMF629 with a href to TMF622?

    Or should I define the JSON scheme in Characteristic using the "@schemaLocation" key/pair (@schemaLocation isn't specifically documented as part of characteristic). For example:

    {
       "characteristic":[
          {
             "@schemaLocation": "... href to JSON schema defining hardware...",
             "name":"hardware",
             "valueType":"objectArray",
             "value":[
                {
                   "id":"NANOSIM",
                   "description":"NANO SIM"
                },
                {
                   "id":"IPHONE6",
                   "description":"iPhone 6"
                }
             ]
          }
       ]
    }

    I understand TMF is pretty flexible but I want to ensure whatever is delivered absoluatly follows best practices.

    Thanks in advance,



    ------------------------------
    Thomas O Donnell
    MDS Global Ltd
    ------------------------------



  • 17.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Mar 10, 2023 09:40

    Given that you have to return basically product information in your Customer retrieve, I suggest the following:

    • Extend Customer resource with a property product of type Product - take the schema from TMF637 Product Inventory swagger
    • Use the existing characteristic array property of Product to communicate the structure above

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



  • 18.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Mar 14, 2023 04:21

    Thanks Jonathan!



    ------------------------------
    Thomas O Donnell
    MDS Global Ltd
    ------------------------------



  • 19.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 07, 2023 09:42
    Edited by Marlon Almazan Apr 10, 2023 14:39

    Hi Everyone,

    Somewhat of a related question. I'm trying to model a somewhat complex service and have landed on something like this. Would this be considered a valid extension? 
    Thanks!

    {
    "serviceCharacteristic": [
        {
          "name": "complexObject",
          "value": {
            "anotherObject": {
              "value1": "value1",
              "value2": "valu2",
              "array": [
                "element 1",
                "element 2"
              ]
            }
          }
        }
      ]
    }







  • 20.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted Apr 13, 2023 15:07

    Hi Tony
    It would help if you could give a concrete realistic business example, instead of arbitrary names for which it's difficult to understand semantic meaning.



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