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.
------------------------------
Original Message:
Sent: Jun 18, 2024 03:00
From: Jonathan Goldberg
Subject: TMF688 Event Versioning
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.
------------------------------
Original Message:
Sent: Jun 18, 2024 02:14
From: Andreas Lobenwein
Subject: TMF688 Event Versioning
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
Original Message:
Sent: Jun 17, 2024 15:17
From: Jonathan Goldberg
Subject: TMF688 Event Versioning
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.