Open APIs

 View Only

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

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

    TM Forum Member
    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
    ------------------------------