Do yo know of anyone who can give an explanation of my above questions? Whilst in theory and on paper it sounds good it doesnt really explain how this is meant to work in practice between squads designing and building these apis and squads that are designing and building applications that consume these apis
Original Message:
Sent: Feb 21, 2023 11:05
From: David Whitfield
Subject: TMF641 creating milestone events with meta data
Hey @Jonathan Goldberg
Hope you dont mind but i thought to bring my understanding of how we use @type back here as some time back i'd be pondering how to use it properly.
In my business my API consumers want a really clear interface definition for them to consume at design time and build their client applications to.
My problem in the case of @type : 'ExtendedMilestone' If i had not included this in the swagger of my TMF641 API (which i think is the intention of TMF.... i.e. take it off the shelf from the Open API table and never change it) then how when i add in this extended model do i provide this understanding and schema to my client?
At the end of the day they cannot design or build anything to the extended content it provides if the first time they or their software knows about it is receiving an API response which includes a container which has
"@type" : "ExtendedMilestone","schemaLocation" : "//api/v1/schema/ExtendedMilestone"
So is this a case of saying the intention of TMF for polymorphic extensions is to: -
- At Design time create
- A TMF641 schema which exactly matches the one in the Open API table
- Create lots of other schema documents (not APIs) where each one contains a polymorphic extension subclass (ExtendedMilestone, DavesMilestone, AnotherMilestone)
- Provide both the TMF641 & your additional 'schema documents' to your API consumers at design time for them to build to
- Whenver you add a new polymorphic extension subclass (ExtraMilestone) just issue the new schema document
- At run time
- deliver the @type/@baseType attritbutes along with schemaLocation to facilitate ????
- This is what i dont understand as i've given the API consumers the schema document at design time so they can consume into their client and build a client library to handle it, yes the @type/@baseType tell them which of their client classes they could cast it to but how do they use the link?
In a sense I'm thinking that i still havent quite wrapped my head around what the thinking is on the approach for these extensions because if the above isnt true then i'm not really sure how clients are meant to adopt and write logic based on the attributes contained in the extensions.
------------------------------
David Whitfield
TalkTalk Group
Original Message:
Sent: Jan 20, 2022 17:14
From: David Whitfield
Subject: TMF641 creating milestone events with meta data
Hey @Ludovic Robert,
One thing i struggle to to wrap my head around with the TMF API's is how a client that consumes my API's Swagger (which seems is only meant to describe the base milestone from what i can see) comprehends the structure of the extendend milestone. This same confusion applys to any extension of the TMF base objects.
I think that the answer is they only know at the point of receiving a response and have to identify that the schema does not live in the existing prebuild client classes (Generate from the swagger) but there is a link to the schema included in the object which needs to be used for 'just in time' object comprehension. I'm just not sure how in reality this works and how the client does this?
Is there any chance any one has an example of what the server sends and how the client interprets this?
So far we have considered to include both schemas (Milestone and ExtendedMilestone) in the swagger definition and then use oneOf (below) but i'm well aware this doesnt offer the server the licence to deliver a new milestone derived type without a new API version.
Note - we use YAML to describe our API's not JSONSchema.
type: arrayitems: oneOf: - $ref: '#/components/schemas/Milestone' - $ref: '#/components/schemas/ExtendedMilestone'
------------------------------
David Whitfield
TalkTalk Group
Original Message:
Sent: Jan 12, 2022 09:48
From: Ludovic Robert
Subject: TMF641 creating milestone events with meta data
Just an idea, David, but perhaps extending the model with a StatusChange class. Look what we have in TMF621 to track trouble ticket state change.
You keep as it the state in the order and add statusChange attribute targeting StatusChange class. Then you can extend this one to your purpose.
BTW I will not recommend using Characteristic without CharacteristicSpecification somewhere. Look for service, we have serviceCharacteristic in 641/638 which are defined as ServiceCharacteristicSpecification in 633.
------------------------------
Ludovic Robert
Orange
My answer are my own & don't represent necessarily my company or the TMF
Original Message:
Sent: Jan 12, 2022 09:23
From: David Whitfield
Subject: TMF641 creating milestone events with meta data
Hey @Ludovic Robert,
thanks for coming back to me on this, I have whilst pondering on this over the last couple of days come to a similar conclusion over '@type'. Your similar view is very helpful.
I think on the meta data node its purely due to having 0..* 'codes' per milestone (clearly the base milestone can be used if there is no meta data). The other option i had thought of in the interim was to add a 'milestoneCharacterisitcs' node to this type of milestone and therefore this would provide future extensibility should any other data be needed.
Whilst this does give a reasonable answer for the milestones i dont see an option to link a similar set of data to a state update given that the state note in the order line and order is just a string and not a complex type, would you have any thoughts on that?
many thanks
Dave
------------------------------
David Whitfield
TalkTalk Group
Original Message:
Sent: Jan 12, 2022 07:39
From: Ludovic Robert
Subject: TMF641 creating milestone events with meta data
Hello David
For me, you should have a @type attribute in the Milestone class to be compliant with TMF extension model.
You have created a specialization of the Milestone, and it needs to be present in the payload.
Something like this (providing example of using your notification and standard one):
{ "id" : "xyz123", "@type" : "ServiceOrder", //other service order attributes "milestone" : [ { "id" : "dffokfl38734897598", "name" : "SomeTypeOfMilestoneUpdate", "message" : "here a extended milestone", "@type" : "ExtendedMilestone", "metadata" : [ { "code" : "abc123", "description" : "useful description", "reason" : "explain why", "category" : "categoryA" }, { "code" : "xyz456", "description" : "useful description", "reason" : "explain why", "category" : "categoryB" } ] }, { "id" : "45", "name" : "SomeTypeOfMilestoneUpdate", "message" : "here a standard milestone", "@type" : "Milestone", } ]}
This @type is used a discriminator.
After regarding use of a specific Metadata node or directly adding code/description/reason/category I haven't specific thoughts.
Hope it helps
Ludovic
------------------------------
Ludovic Robert
Orange
My answer are my own & don't represent necessarily my company or the TMF
Original Message:
Sent: Jan 07, 2022 12:06
From: David Whitfield
Subject: TMF641 creating milestone events with meta data
Hi All,
We have a requirement around supplying metadata for a milestone when creating these types of event notification. This meta data takes the form of a collection of objects that are associated to a milestone. I was trying to think about a way of representing these within the existing data model and not extending the TMF API.
Our order management system would recieve inbound updates from fibre access providers detailing the status of the fullfilment in their systems. At this point we have a need to publish this information out to allow subscribers (namely business systems) to understand the latest update.
Whilst the service order milestone seems appropriate (and is the approach we were intending to take), it would appear an extension would be required unless anyone has any good suggestions on how this might be achieved?
The data would look something like this if we extended milestone but not sure how compliant this approach is or if others have faced this challenge?
{ "id" : "xyz123", "@type" : "ServiceOrder", //other service order attributes "milestone" : [ { "id" : "dffokfl38734897598", "name" : "SomeTypeOfMilestoneUpdate", "message" : "Something has happened to the order or 1 of the line items which will be interesting to some subscribers", "metadata" : [ { "code" : "abc123", "description" : "useful description", "reason" : "explain why", "category" : "categoryA" }, { "code" : "xyz456", "description" : "useful description", "reason" : "explain why", "category" : "categoryB" } ] } ]}
thanks in advance for any thoughts/guidance
------------------------------
David Whitfield
TalkTalk Group
------------------------------