Open APIs

 View Only
  • 1.  Can any API type be extended? Are only certain types intended for extension?

    TM Forum Member
    Posted Apr 06, 2020 04:51
    Hello,

    The extension mechanism described in TMF630 allows us to extend the schema of a type to add additional information.
    Are we free to extend any type using this mechanism?

    The reason I ask is because the schema files published on GitHub only define the "@type", "@baseType" and "@schemaLocation" properties on some of the types, not all. Is this just an accident of authoring, or by design? I can't see anything in the specifications I have read that limits schema extension/polymorphism.

    E.g. in TMF646 Appointing:
    type TimeSlot has the properties "@type", "@baseType" and "@schemaLocation"
    type TimePeriod has none
    Is this just some arbitrary choice of the author, or is the intention that TimeSlot is an extension point and TimePeriod is not?
    I can't see anything in the TMF646 specification that explicitly limits extension.

    thanks, Alasdair

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------


  • 2.  RE: Can any API type be extended? Are only certain types intended for extension?

    TM Forum Member
    Posted Apr 07, 2020 01:44

    Alasdair,

    If you look at the schemas for these two types (in current repo) you will find that they both include:

       "allOf": [
           {
               "$ref": "../Common/Entity.schema.json#Entity"
           }
       ]

    Including the Entity schema makes it extensible.



    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 3.  RE: Can any API type be extended? Are only certain types intended for extension?

    TM Forum Member
    Posted Apr 20, 2020 09:18
    Hi Alasdair, Vance

    A small refinement - complex data types (such as TimePeriod, Duration, Quantity, etc.) should not be extensible (in fact we just reiterated this point in an Open API team meeting today :) ). Real business entities (such as Timeslot for an appointment) should of course be extensible.

    And additionally we have created a dedicated schema Extensible that includes only the @ attributes - API designers are expected to do allOf Extensible for ​those schemas which they consider to be extensible.

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



  • 4.  RE: Can any API type be extended? Are only certain types intended for extension?

    TM Forum Member
    Posted Apr 23, 2020 04:39
    Thanks Jonathon,

    Is there any document detailing this split? I guess it's fairly self-evident but would be handy to have a list.
    I guess Extensible will appear in the public GitHub repos as and when APIs are updated?



    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 5.  RE: Can any API type be extended? Are only certain types intended for extension?

    TM Forum Member
    Posted Apr 23, 2020 10:28
    Hi Alasdair
    Unfortunately there is not currently any published guideline on this demarcation. I gave you examples off the top of my head, intuitively it should be very clear, although we may find that for one or two schemas there could be a grey area.

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