Open APIs

 View Only
  • 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 28 days ago
    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 27 days ago
    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 26 days ago
    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 25 days ago
    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 25 days ago
    Thanks a lot. That is very helpful information.

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



  • 7.  RE: Characteristics Schema - Value Type

    TM Forum Member
    Posted 19 days ago
    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 18 days ago
    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 18 days ago
    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 15 days ago
    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.
    ------------------------------