Open APIs

 View Only

  • 1.  Related[Entity] vs. Related[Entity]RefOrValue schemas

    Posted Jan 30, 2023 11:57
    Edited by Carlos Prados Jan 30, 2023 12:18
    Hi all,

    I have the following doubt after reviewing TMF630 Open API desing guidelines and the usage of the Json schema patterns Related[Entity] and Relted[Entity]RefOrValue that is present in many Open APIs.

    According to TMF630 REST API Design Guidelines Part 7 (JSon Schema Guidelines):

    (A)

    Related[Entity]RefOrValue:
    • MUST be built from [Entity] schema + [Entity]Ref schema (use of allOf keyword in Swagger 2.0)
    • MUST have a role attribute (mandatory)
    • isRef attribute MUST NOT be present in the schema
    • Attributes @type, @schemaLocation & @referredType are related to the contained entity and not the Related[Entity]RefOrValue class itself.

    Related[Entity]:
    • MUST include a reference to EntityRef schema (use of allOf keyword in Swagger 2.0). It is important to consider that the information provided in the @type, @baseType, @schemaLocation and @referredType are relevant to the targeted entity and not for the related[Entity] schema itself.
    • The role attribute MUST be mandatory
      • Exception: In RelatedParty schema, the role is not mandatory because provided id could refer to a PartyRole id – in this case the Role could be blank. Please note that for RelatedParty the @referredType MUST be mandatory
    • Related[Entity]Ref schema MUST not exist!

    So Related[Entity] is to describe a reference to object of certain [Entity] with a role, while a Related[Entity]RefOrValue is to represent either a reference or an object by value, that is related to the base entity and with a role that is played among both entities.
    So far, so good but... If you go to TMF630 Design Guidelines part 2 on extensions, you can read:

    (B)

    All resources defined within an API MAY be extended, therefore attributes @type, @baseType and @schemaLocation MUST be supported optionally in the structure definition of all resources. Those resources that are not expected to be extended are not required to explicitly include the attributes as part of the resource structure definition in the API spec documentation.

    So I am thinking if it is OK to mix (A) and (B) as follows:

    According to (A) a Related[Entity] have @type, @baseType and @schemaLocation so nothing is preventing this class to be subclassed according to (B) and a Related[Entity]RefOrValue would already be a subclass of Related[Entity], as it has [Entity]Ref as part of it schema...
    Now change [Entity] with "Party" or "Place". Does that mean that it is correct to pass a "RelatedPlaceRefOrValue" every time you see an attribute of type "RelatedPlace" in an Open API? An object of type "RelatedIndividualRefOrValue" or "RelatedOrganizationRefOrValue" can go on every attribute of type "RelatedParty"?

    And going further, any Related[Entity]RefOrValue, can fit inside an attribute of type RelatedEntity, like for instance if one defines RelatedTroubleTicketRefOrValue, it could go in an attribute of type "RelatedEntity"?
    From my point of view the polymorphic pattern implicitly allows this and from a practical point of view this allows much more flexible use of the APIs in many scenarios where the API implementations are abstractions around the interfaces to backends that are legacy and whose model cannot be changed, but can be wrapped with the corresponding TMF entities.
    Let me know what you think.

    ------------------------------
    Carlos Prados
    Vodafone Group
    ------------------------------


  • 2.  RE: Related[Entity] vs. Related[Entity]RefOrValue schemas

    Posted Sep 11, 2024 06:12

    Hi All,

    It was ashame that this post didn't receive a reply because I am faced with a similar challenge whereby in an API (621 troubleTicket, but that isnt overly important) I have a requirement for our API client to be able to submit contact details as part of ticket submission.

    In my view there are two options for this solution: -

    A - Post an 'Individual' sub class to a party management API, Then post a ticket with the PartyRef utilising the id generated from the first call

    B - Extend the relatedParty from a PartyRef to a PartyRefOrValue (in v4 terminology or oneOf PartyRef/PartyValue

    Whilst i think that the answer is from a purest perspective (and means no extension) the better technical one this is not accepted as an approach by the API consumers and the desire is for option B.

    So I was looking for some guidance on how is the best approach to 'upgrade' something from the base TMF specification that only allows a ref to allow a value also, Any help on the way forward would be good as what I have seen in TMF630 concentrates on how to use polymorphism to make subclasses of existing base classes (i.e. Resource --> Physical Resource --> MyPhysicalResource) and thats not really my need here.

    thanks in advance for any help with this

    Dave



    ------------------------------
    David Whitfield
    PlatformX Communications (PXC)
    ------------------------------



Related Content