Open APIs

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.

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.

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,

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.

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'

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,

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

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

HI all,

We've released a fix for TMF629 Customer Management missing Characteristic subclasses : OAS

TMF629 Customer Management API OPEN API SPECIFICATION v5.0.1  API https://www.tmforum.org/oda/open-apis/directory/customer-management-api-TMF629/v5.0.1 

Regards,

Heidi

------------------------------
Heidi Lobecker
TM Forum
Program Manager
Technology, Data & Digital Experience
------------------------------