Open APIs

Expand all | Collapse all

Extension Pattern - changing schema during runtime

  • 1.  Extension Pattern - changing schema during runtime

    Posted 19 days ago
    Hello,
    I have a question about changing schema during runtime. In our system, we have the possibility of adding new classes and attributes (and extending existing classes as well). According to this, we assume that we should change schema during runtime. So we can assume that the API client should always grab schema definition on every request before he processes returned object data?

    ------------------------------
    Paul Stanek
    TO BE VERIFIED
    ------------------------------


  • 2.  RE: Extension Pattern - changing schema during runtime

    TM Forum Member
    Posted 19 days ago
    Hi Paul
    A bit difficult to answer this question without more details. If you can do so without exposing sensitive IP, perhaps you could give the community a concrete example of the problem area you are dealing with (ideally with real business names and not ClassA, EntityB, etc.). That way you've a better chance of getting some advice and feedback.

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



  • 3.  RE: Extension Pattern - changing schema during runtime

    Posted 18 days ago
    Hi,
    Thanks, Jonathan for your interest. I will try to be more specific.
    Let's say that we have an Equipment entity from TMF SID specification. And we using Resource Inventory Management API for maintaining this entity. Equipment inherits from Physical Resource. Next, this Physical Resource inherits from Resource. All this hierarchy and Entities are all known so we hardcode this in our systems and exposed it via API schema definitions (YAML file). But during using our Resource Inventory Application we are giving user possibility to crate own entities.  So for example he creates a new Entity: Equipment Type1 which inherit from the entity Equipment. And new attributes are added to Equipment Type 1. How we should expose this new entity during runtime. Should we change the schema definition? And can we assume that client who uses our API is obligated to refresh schema on every request?

     


    ------------------------------
    Paul Stanek
    TO BE VERIFIED
    ------------------------------



  • 4.  RE: Extension Pattern - changing schema during runtime

    TM Forum Member
    Posted 2 days ago
    This is my interpretation of the specs:

    The custom definitions must be extensions of the definitions in the spec. I.e. no breaking changes. So a client that can handle the specifications should be able to handle your specific payloads, as far as generic behaviour goes, without knowing your definition.

    TMF630 says that an extended definition should include a link to the definition, see TMF630 part 2, which gives the example:
    "@type": "Equipment",
    "@baseType": "PhysicalResource",
    "@schemaLocation": "//server:port/resourceInventoryManagement/schema/Equipment.yml", <-- I think your definition goes here
    I would think the client has some definition resolver that will lookup the schemaLocation to down load the definition if not already cached.
    That is your hook into customised behaviour. How that behaviour is realised is an exercise for the (virtual) whiteboard and water cooler.

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



  • 5.  RE: Extension Pattern - changing schema during runtime

    Posted 2 days ago
    Edited by Paul Stanek 2 days ago
    Thanks,
    Alasdair for your answer. I come to the conclusion that definitions should not be changed during runtime. And I found out on the forum that API should have one main file with schema definition and attribute @schemaLocation in fact points to the main file. It looks something like that:
    "@schemaLocation": "//server:port/resourceInventoryManagement/schema/ApiSchemaFile.yml#/definitions/Equipment.




    ------------------------------
    Paul Stanek
    TO BE VERIFIED
    ------------------------------



  • 6.  RE: Extension Pattern - changing schema during runtime

    TM Forum Member
    Posted 2 days ago
    Do you have any link to where the spec says everything must be in one file?

    TMF630 talks about a "Home Document", but that is just a jumping off point.

    In any case, even if you have one notional document I would surprised if it stayed static for all time - the Home Document is not intended to be static, I don't see why definitions needs to be static. You can't have breaking changes, you need to manage versioning and update - but that is one of the reasons you use REST in the 1st place surely?

    Hopefully someone can cast light on this?

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



  • 7.  RE: Extension Pattern - changing schema during runtime

    Posted 2 days ago
    Edited by Paul Stanek 2 days ago
    No, I don't have link to the spec for this. I find out this from TMF forum:

    https://engage.tmforum.org/communities/community-home/digestviewer/viewthread?GroupId=31&MessageKey=5921f38f-6376-4f54-a4ad-d463a47940d2&CommunityKey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer&ReturnUrl=%2fcommunities%2fcommunity-home%2fdigestviewer%3fcommunitykey%3dd543b8ba-9d3a-4121-85ce-5b68e6c31ce5%26tab%3ddigestviewer
    "The thing to understand is that value of @schemaLocation isn't just a path to a file which contains ​​some definitions but the canonical link of the schema definition of the individual type given in the value of @type.  ​

    In the example below there is a schema definition for MyType available in a file which is accessed using the URL fragment #definitions/MyType. The file may contain many schema definitions. 

    "@type": "MyType",
    "@schemaLocation": "path_to_file#/definitions/MyType",



    ------------------------------
    Paul Stanek
    TO BE VERIFIED
    ------------------------------



  • 8.  RE: Extension Pattern - changing schema during runtime

    Posted 2 days ago
    And you are right Alasdair. I did not mean that file should be static. It can be generated and can change with some restrictions according to the versioning rules. 


    ------------------------------
    Paul Stanek
    TO BE VERIFIED
    ------------------------------