Open APIs

 View Only
  • 1.  Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 21 days ago

    Hi Everyone,

    I'm reviewing the latest version 5 specs for 632 (party management) and 629 (customer management).
    I've noticed that while 632 provides subclassed characteristics (string, bool, number etc.) 629 does not.


    TMF632 Party Management v5

    Characteristic:
      allOf:
        - $ref: '#/components/schemas/Extensible'
        - type: object
          description: Describes a given characteristic of an object or entity through a name/value pair.
          properties:
            id:
              type: string
              description: Unique identifier of the characteristic
            name:
              type: string
              description: Name of the characteristic
            valueType:
              type: string
              description: Data type of the value of the characteristic
            characteristicRelationship:
              type: array
              items:
                $ref: '#/components/schemas/CharacteristicRelationship'
      discriminator:
        propertyName: '@type'
        mapping:
          Characteristic: '#/components/schemas/Characteristic'
          StringCharacteristic: '#/components/schemas/StringCharacteristic'
          StringArrayCharacteristic: '#/components/schemas/StringArrayCharacteristic'
          ObjectCharacteristic: '#/components/schemas/ObjectCharacteristic'
          ObjectArrayCharacteristic: '#/components/schemas/ObjectArrayCharacteristic'
          NumberCharacteristic: '#/components/schemas/NumberCharacteristic'
          NumberArrayCharacteristic: '#/components/schemas/NumberArrayCharacteristic'
          IntegerCharacteristic: '#/components/schemas/IntegerCharacteristic'
          IntegerArrayCharacteristic: '#/components/schemas/IntegerArrayCharacteristic'
          FloatCharacteristic: '#/components/schemas/FloatCharacteristic'
          BooleanCharacteristic: '#/components/schemas/BooleanCharacteristic'


    TMF629 Customer Management v5

    Characteristic:
      allOf:
        - $ref: '#/components/schemas/Extensible'
        - type: object
          description: Describes a given characteristic of an object or entity through a name/value pair.
          properties:
            id:
              type: string
              description: Unique identifier of the characteristic
            name:
              type: string
              description: Name of the characteristic
            valueType:
              type: string
              description: Data type of the value of the characteristic
            characteristicRelationship:
              type: array
              items:
                $ref: '#/components/schemas/CharacteristicRelationship'
          discriminator:
            propertyName: '@type'
            mapping:
              Characteristic: '#/components/schemas/Characteristic'


    This appears to leave 629 without a "value" property on its characteristics.

    My use-case is representing a customer with some related information, as so:

    TMF629 GET /customer/{id}

    {
        "@type": "Customer",
        "role": "Customer",
        "id": "c1234567-d89b-42c3-b456-556642440000",
        "href": "/customerManagement/v5/customer/c1234567-d89b-42c3-b456-556642440000",
        "name": "Coffee Do Brazil",
        "characteristic": [
            {
                "@type": "Characteristic",
                "name": "Segment",
                "value": "Enterprise", // not in the spec
                "valueType": "string"
            }
        ],
        ...
    }


    I'd greatly appreciate it if anyone could shed some light on this.



    ------------------------------
    George Beatty
    Aussie Broadband Limited
    ------------------------------


  • 2.  RE: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 21 days ago

    Hi George

    I'm afraid it's a defect, and I'll be opening a report to get this fixed. The OAS file for TMF629 should treat characteristics in the same way as for TMF632. You could in the meantime try making a private fix to the OAS file, but there's no guarantee that your private fix will be identical to the official correction when it comes.

    I'll try to get this expedited but I cannot promise.



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



  • 3.  RE: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 20 days ago

    Hi Jonathan,

    as far as we know in our implementations of TMF v5 APIs, TMF653 and TMF697 suffer the same issue. We fixed it internally by adding the missing definitions (from an API that was ok).

    Best regards,



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



  • 4.  RE: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 20 days ago

    Another issue we noticed on these APIs (I already posted it some time ago on the TMForum) is that the Fields request parameter is missing from the retrieveXXX operations.



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



  • 5.  RE: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 20 days ago

    Thanks Frederic for these alerts.

    I've checked the beta-published OAS files for 653 and 697, and they appear to be correct, both in the area of characteristics and for the Fields directive on retrieve. Perhaps you had an earlier version?

      '/serviceTest/{id}':
        get:
          tags:
            - serviceTest
          summary: Retrieves a ServiceTest by ID
          description: >-
            This operation retrieves a ServiceTest entity. Attribute selection enabled for all first
            level attributes.
          operationId: retrieveServiceTest
          parameters:
            - $ref: '#/components/parameters/Id'
            - $ref: '#/components/parameters/Fields'
    

        Characteristic:
          allOf:
            - $ref: '#/components/schemas/Extensible'
            - type: object
              description: Describes a given characteristic of an object or entity through a name/value pair.
              properties:
                id:
                  type: string
                  description: Unique identifier of the characteristic
                name:
                  type: string
                  description: Name of the characteristic
                valueType:
                  type: string
                  description: Data type of the value of the characteristic
                characteristicRelationship:
                  type: array
                  items:
                    $ref: '#/components/schemas/CharacteristicRelationship'
          discriminator:
            propertyName: '@type'
            mapping:
              Characteristic: '#/components/schemas/Characteristic'
              BooleanArrayCharacteristic: '#/components/schemas/BooleanArrayCharacteristic'
              BooleanCharacteristic: '#/components/schemas/BooleanCharacteristic'
              IntegerArrayCharacteristic: '#/components/schemas/IntegerArrayCharacteristic'
              IntegerCharacteristic: '#/components/schemas/IntegerCharacteristic'
              NumberArrayCharacteristic: '#/components/schemas/NumberArrayCharacteristic'
              NumberCharacteristic: '#/components/schemas/NumberCharacteristic'
              ObjectArrayCharacteristic: '#/components/schemas/ObjectArrayCharacteristic'
              ObjectCharacteristic: '#/components/schemas/ObjectCharacteristic'
              StringArrayCharacteristic: '#/components/schemas/StringArrayCharacteristic'
              StringCharacteristic: '#/components/schemas/StringCharacteristic'


    ------------------------------
    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: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 20 days ago

    Hi Jonathan,

    Thx for the quick reply. Indeed I downloaded these resources a couple of months ago. I can also see that there are more resources available for these APIs as well (like the user guide) ;)

    Best regards,



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



  • 7.  RE: Characteristic Representation in 632 vs. 629 v5 Specifications

    TM Forum Member
    Posted 20 days ago
    Edited by George Beatty 20 days ago

    Thanks for the clarification, Jonathan. I'll update our spec locally. 
    I think I'll take the definition from TMF669 Party Role Management. Since Customer is a subclass of PartyRole, they should have very similar characteristic implementations. I understand that 669 and 632 should have identical implementations. Likely, these implementations should be the same across the entire API.



    ------------------------------
    George Beatty
    Aussie Broadband Limited
    ------------------------------