Open APIs

 View Only
  • 1.  TMF688 Event Versioning

    TM Forum Member
    Posted Jun 17, 2024 09:29

    Hello,

    I am not clear about how events in TMF688 are versioned.

    Scenario:
    A resource server decides to upgrade his resource model with breaking changes supporting still the old version in parallel for a transition period for old consumers.
    In case of API access a consumer is able to choose via URI versioning properly between the 2 major versions of provided API spec.

    In TMF630,Part1,Chapter 11.1 following is stated "... The versioning is applied uniformly to all the entities under a versioned API. That is, it is assumed that
    entities under the management scope of the API are all aligned with the same version ..."

    Question: What is the concept in the event management TMF688 to indicate a clear versioning for consumers/listeners?

    Follow-up Question:
    Usually a consumer does provide a single technical endpoint for receiving all events. So, URI versioning does not work, a consumer needs to identify during receiving which version the payload refers to.

    Regards
    Andreas Lobenwein
    Telefonica Germany GmbH & Co. OHG



    ------------------------------
    Andreas Lobenwein
    Telefonica Germany GmbH & Co. OHG
    ------------------------------


  • 2.  RE: TMF688 Event Versioning

    TM Forum Member
    Posted Jun 17, 2024 15:18

    Hi Andreas

    These are great questions, and it does seem that the Open API guidelines did not cover this. BTW this is not related specifically to the event API TMF688, but rather to any message-mediated asynchronous interaction, such as the older hub subscribe mechanism, or even the very new async APIs that have started to be published on the beta Open API table.

    There are many scenarios to consider here. Just one example - a message format was changed in a non-compatible way, say by removing a property. There will be some (new) consumers that will be able to read and process the new message version, while there will be other (old) consumers that will not be able to deal with the new version. The implication is that the message provider needs to write the message in both formats, and consumers need to be written in such a way that they are able to extract and process the version of the message that they support.

    A full treatment would need a detailed discussion within the Open API team, so I plan to raise an issue for this discussion. Due to DTW I cannot imagine anything will happen immediately.



    ------------------------------
    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: TMF688 Event Versioning

    TM Forum Member
    Posted Jun 18, 2024 02:14

    Hi Jonathan,

    thx for looking into this question.

    What do you think about using the @schemaLocation attribute in TMF688 Event Structure for indicating the "version" implicitly by including it into the URI path of the location value?
    For me it looks TMF compliant and fitting to TMF intentions, doesn't it?

    Proposal e.g.
    POST /client/listener
    {
    "@schemaLocation": "./schema-registry/API-CONTEXT-OF-EVENT/v1/event-schema.json"
    "eventType": "EVENT_TYPE"
    "event": {
    EVENT BODY
    },
    }

    POST /client/listener
    {
    "@schemaLocation": "./schema-registry/API-CONTEXT-OF-EVENT/v2/event-schema.json"
    "eventType": "EVENT_TYPE"
    "event": {
    EVENT BODY
    },
    }

    A more customized/proprietary variant is to add into event analyticCharacteristic a version indicator key-value pair.
    I tend to the @schemaLocation.

    Regards
    Andreas.



    ------------------------------
    Andreas Lobenwein
    Telefonica Germany GmbH & Co. OHG
    ------------------------------



  • 4.  RE: TMF688 Event Versioning

    TM Forum Member
    Posted Jun 18, 2024 03:00

    I'm not sure about your suggestions, Andreas. Possibly the most robust way would be to add a version property to the event schema itself. So it would appear in the payload directly , such as:

      "eventType": "ProductOfferingCreateEvent",

      "version": "v4"

    I've asked for an internal discussion with the team, let's see what happens.



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



  • 5.  RE: TMF688 Event Versioning

    TM Forum Member
    Posted Sep 04, 2024 08:25

    Schema versioning is an important topic in an event driven architecture if you want to continue to benefit from the decoupled nature of such an architecture.  The folks over at Confluent have some good resources in their Schema Registry documentation (among others):

    Schema Evolution and Compatibility for Schema Registry
    JSON Schema Compatibility Rules

    The following blog (linked from the resources above) is a decent introduction:

    Understanding JSON Schema Compatibility

    In terms of the evolution the TMF688 events, I would think that the @schemaLocation attribute within the event sub-resource would be the place to do the versioning:

    {
        "@type": "AlarmCreateEvent",
        "@schemaLocation": "http://xx/Event.schema.json",
        ...
        "event": {
            "alarm": {
                "@type": "alarm",
                "@schemaLocation": "http://../registry/Alarm.VERSION_HERE.schema.json",
                ...
            }
        }
    }

    A reason to use the @schemaLocation within the event sub-resource rather than the top level is that the event is a generic container that doesn't necessarily change when an event sub-resource changes.  That said, additional versioning attributes such as those suggested might help with querying/filtering.



    ------------------------------
    Graham Agnew
    CSG Systems, Inc.
    ------------------------------