Open APIs

Expand all | Collapse all

RefOrValue pattern & polymorphic mechanisms

  • 1.  RefOrValue pattern & polymorphic mechanisms

    TM Forum Member
    Posted Dec 04, 2020 07:44
    Hello,
    I have a general question around the RefOrValue pattern & API documentation itself:

    Taking TMF645 as an example, we have there the element ServiceRefOrValue.
    Within the QueryServiceQualification resource, we can see below association:

    QueryServiceQualification  ==(searchCriteria/serviceQualificationItem)==>  ServiceQualificationItem ==(service)==> ServiceRefOrValue..

    So, it's clear that ServiceQualificationItem will point to a Service element either by reference or by value (i.e.: usage is clear).

    Anyways, in the specification, we can see that:
    - ServiceRefOrValue is explicitly declared in the API. So, in this API documentation, in theory we have a predefined @type for ServiceRefOrValue.
    - ServiceRef is not explicitly declared in the API. So, in this API documentation, we don't have a predefined @type for ServiceRef.
    - Service element is not explicitly declared in the API. So, in this API documentation, we don't have a predefined @type for Service.

    Question is:
    When returning a ServiceRefOrValue, which @baseType & @type should we use?

    Seems rational to think that we should forget about the refOrValue notation and use @type & @baseType pointing to either
    reference or value element (e.g.: @type = ServiceRef, @baseType = Service...)
    But, existing API documentation may lead us to use ServiceRefOrValue under @type and, under @baseType as we have no examples.

    ​​​​Thanks.​​​​​​

    ------------------------------
    Marcos Donato da Silva
    Ericsson Inc.
    ------------------------------


  • 2.  RE: RefOrValue pattern & polymorphic mechanisms

    TM Forum Member
    Posted Dec 07, 2020 03:30
    Hello Marcos
    Moving forward to the V5.0 release we're working to solve/clarify this pattern.
    As of now the team direction for the xxxxRefOrValue is to enforce the use of the @type as discriminator (@type attribute must be an attribute of xxxxRefOrValue ).
    Then in the swagger both xxxx (used for value) and xxxxRef (used for reference) will be in the swagger.
    Last we plan to add in the swagger an allOf xxxxRefOrValue  in xxxx and xxxxRef schemas to avoid any issue with code generator.

    This is still work in progress and we're assessing this pattern - it could change - but this to share with you the direction. Of course we're working also to document this in the Design Guideline document.

    Hop it helps
    Ludovic


    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 3.  RE: RefOrValue pattern & polymorphic mechanisms

    TM Forum Member
    Posted Dec 07, 2020 12:24
    Thanks Ludovic.
    So, we can assume that in the below extract from TMF645, Service is a synonym of ServiceRefOrValue, right?
    Thanks,

    ------------------------------
    Marcos Donato da Silva
    Ericsson Inc.
    ------------------------------