Open APIs

 View Only

  • 1.  TMF 633 Characteristic valueType Object Array

    Posted Sep 19, 2023 06:38
    Edited by Jay Hamilton Sep 19, 2023 06:53

    I am defining TMF 633 service specification characteristics. I have two (phone numbers and CPE ports) that have a max cardinality greater than 1 such that each can have multiple instances. However, they are related and should be paired together.  Still learning how to model so bare with me. To solve this I quickly jumped to trying to figure out how to introduce an objectArray as a characteristic type. I then saw some comments about TMF version 5 as well as the use of combined specifications. What is the current best guidance? Or am I missing something? Ultimately, I expect an array of objects, that look like the following, get sent in as part of the request body in a TMF 641 serviceOrder request. Am also considering if establishing a charactersticRelationShip between the two separate characteristics is sufficient:

    serviceCharacteristic: [
   { 
       name: tnToCPEPortMapping,
       value:  [
          {
              tn: xxxx,
              port:xxxx
          },
          {
              tn: xxxx,
              port:xxxx
           }
    },
    {
         name: someOtherCharactersticName,
         value: someStringValue
     }
]






  • 2.  RE: TMF 633 Characteristic valueType Object Array

    Posted Sep 20, 2023 01:43

    Hi Jay

    You could try looking IG1163B_SID_Clarification_CharacterSpec_and_Value document (Section 3) for the use of characteristic relationship.

    That said, since you are only trying to group telephone number to port, then using an objectArrayCharacteristic is probably fine.  You need to add the @type metadata in the value though to discriminate the type of value accordingly.

    Hope this helps.  Good luck!



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------



  • 3.  RE: TMF 633 Characteristic valueType Object Array
    Best Answer

    Posted Sep 21, 2023 03:19

    Hi Jay,

    In the version 4 of the TMF633 API, you would use the valueType: "object" and specify the "valueSchemaLocation" property to link to a JSON schema defining your object.

    Something like that:

    {
    "configurable":  true,
    "description":  "TN to CPE port mapping",
    "maxCardinality":  XX,
    "minCardinality":  0,
    "name":  "tnToCPEPortMapping",
    "valueType":  "object",
    "@valueSchemaLocation":  "http://[hostname]/json-schemas/tnToCPEPortMapping-1.0.schema.json"        
}
    maxCardinality: XX > 1 for a list
    minCardinality among other things control the optional/mandatory aspect of the characteristic
    So basically, the valueType holds the type of the value (if maxCardinality == 1) or value of the elements within the array (if maxCardinality > 1).
    If valueType is object, then you have to specify the valueSchemaLocation property.
    Translated to a TMF 638 characteristic, you would have indeed:
    { 
    "name": "tnToCPEPortMapping",
    "value": [
        {
            "tn": "xxxx",
            "port": "xxxx"
        },
        {
            "tn": "xxxx",
            "port": "xxxx"
        }
    ]
}

    Hope that helps,

    Best regards,



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



  • 4.  RE: TMF 633 Characteristic valueType Object Array

    Posted Sep 21, 2023 04:34

    I agree with Frederic and didn't want to reference TMF630 Part 2 Design Guidelines on polymorphism as the text alongside the example of implementing complex characteristics is misleading.

    2.2 Schema based extension for the Characteristic of an entity

    Assuming that Characteristic/CharacteristicSpec  pattern is used, the following example shows how we can extend an API at run time by adding simple or complex characteristics:

                  "resourceCharacteristic": [{

                                               "name": "physicalPort",

                                                     "valueType":"Object",

                                               "value": {

                                                              "@type": "PhysicalPort",

                                                                   "@schemaLocation": "http://host:port/schema/PhysicalPort.yml,

                                                              "name": "LAN Port",

                                                              "isActive": true,

                                               }

    An example, showing the Characteristic/CharacteristicSpec with the specification defining the complex characteristic definition and its associated payload when instantiating the entity would have made sense before providing an example for dynamic runtime extensions.



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------

    Original Message


  • 5.  RE: TMF 633 Characteristic valueType Object Array

    Posted Sep 29, 2023 03:21

    In version 5 (Gen5) APIs, you will be able to have strongly-typed characteristics and characteristic specs, you can see this in the newly-published v5 specs and Swagger/OAS files at the API table https://www.tmforum.org/oda/open-apis/table

    Service Inventory is published, unfortunately Service Catalog is not yet. But you can see the equivalent in Product Catalog and Inventory, both published in v5.

    So you can have an explicit ObjectCharacteristic or ObjectArrayCharacteristic, for example.



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


  • 6.  RE: TMF 633 Characteristic valueType Object Array

    Posted Oct 09, 2023 03:08

    Hi Jonathan

    For the strongly-typed characteristics in v5, does the @valueSchemaLocation in the CharacteristicSpecification still reference the definition of a complex characteristic (object) and then should the CharacteristicValueSpecification @type=ObjectCharacteristicValueSpecification be used to discriminate the value: object type?

    TMF630 suggests that the Characteristic name field should correspond to the name of the object.  I have noticed some implementations have actually specified the name of the object within the valueType field of CharacteristicSpecification instead.  Presumably either mechansim is still acceptable in v5 right?

    Thanks!



    ------------------------------
    ROCHANA MACHAROEN
    ADVANCED INFO SERVICE PLC. (AIS)
    ------------------------------

    Original Message


  • 7.  RE: TMF 633 Characteristic valueType Object Array

    Posted Sep 29, 2023 06:22
    Edited by Jay Hamilton Sep 29, 2023 06:29

    Dan, your solution is exactly what I implemented. Thanks for the confirmation.

    Jonathan, thanks for that update. Strong typing is what I pursued when I started on this TMF journey 4-5 months ago, then had to back away from it. The info you provided on Version 5 has renewed my interest. 

    Thank You!



    ------------------------------
    Jay Hamilton
    ------------------------------

    Original Message


Related Content