it will be nice having all the Open Apis docs using the format you mentioned, pointing to the right entity, but for now all are referring to a general schema file "https://mycsp.com:8080/tmf-api/schema/Product/VirtualStorage.schema.json"
Original Message:
Sent: May 20, 2024 08:38
From: Vance Shipley
Subject: Swagger and @schemaLocation
Pretty much nobody is using OAS ("swagger") at runtime however it's something I've been a proponent of. One thing we do at SigScale however is to make our own OAS available on the runtime systems (/schema/...) so that developers always have accurate API specifications for the actually implemented APIs. These are subsets/supersets of TM Forum Open API Swagger/OAS crafted by SigScale. We only include the operations supported by the product the specification accompanies (subset) and include any polymorphic extensions implemented by that product (superset).
I think this is the general idea behind Domain Context Specialization (DCS) although not much has been shared so far.
An ambitious developer could code runtime discovery in the application to make multi-vendor integration more automatic. If you apply liberal constraints to types in the schemas it wouldn't be that difficult to filter what could and could not be included an API operation. Dynamically handling polymorphic extensions would be a bit more challenging however if the schemas are liberally documented with description and example attributes you could at least provide a guided experience to the engineers performing the integration.
The problem I see with DCS is that it encourages adding new attributes polymorphically instead of the established pattern for runtime modelling which is the Entity/EntitySpecification pattern. For example the DCS for 5G Slice is a bunch of root level attributes of a Service entity named as used in GSMA NEST. Those all could have been Characteristics in a Service Specification. The argument, I guess, is that it's harder for developers to wrap their heads around that pattern, and it's a bit more cumbersome. The larger issue however is that now your DCS entities are largely incompatible with existing implementations of catalogs, inventories, order management, etc.. While it's true that TMF630 compliant systems should ignore unrecognized attributes, you'd be pretty lucky if an existing inventory system would store them and serve them back! Whereas if, instead of a 5G Slice DCS, you create a 5G Slice Service Specification you can reasonably expect all current and future systems, of all types, to understand and handle the 5G Slice Characteristics.
The purpose of Catalogs is to allow runtime modeling through the creation of Specifications. I'm interested in using OAS at runtime, however that's about lower level service discovery and not replacing the established Entity/EntitySpecification, Characteristic/CharacteristicSpecification patterns.
------------------------------
Vance Shipley
SigScale
Original Message:
Sent: May 20, 2024 07:16
From: David Whitfield
Subject: Swagger and @schemaLocation
Hi All,
I feel like this is a really interesting topic and something i've been wrangling with for some time. Whilst I can see the benefits of parsing a schema location at run time and therefore being able to understand the additional fields that have been added to a subtype. This would be really helpful for when additional information wants to be placed on a screen within say a CRM system for a user to read.
What I struggle with is more on a clients ability to interpret and perform decision logic on attributes that are unbeknown to a developer building to the interface at design time. The first time they would become known would be when they are first interpreted at run time. In our experience so far in trying to adopt TMF APIs for B2B scenarios our clients want clear and defined swagger documents containing all models so API consumers can understand the full interface and not be discovering things at run time. This is also true of different development teams within the organisation.
So I was really interested in anyone else's experiences, and also how this challenge that we have received would be answered by the thinking behind 'runtime discovery' with schemaLocation if @Vance Shipley @Jonathan Goldberg or any others could share their thoughts?
cheers
Dave
------------------------------
David Whitfield
TalkTalk Group
Original Message:
Sent: Jul 21, 2020 12:56
From: Marcos Donato da Silva
Subject: Swagger and @schemaLocation
Hi Vanun,
I was talking about the second option in your reply.
Anyways, for me, Vance's latest reply closes this question for me.
Thank you both.
Regards,
------------------------------
Marcos Donato da Silva
Ericsson Inc.
Original Message:
Sent: Jul 21, 2020 00:26
From: Vance Shipley
Subject: Swagger and @schemaLocation
No, the value of @type should be <<Entity>> (e.g. MyType) which is the same value as the title attribute of the schema.
------------------------------
Vance Shipley
SigScale
Original Message:
Sent: Jul 20, 2020 13:51
From: Marcos Donato da Silva
Subject: Swagger and @schemaLocation
Hey Vance, thanks.
So, using your example, we assume that we can't have this configuration:
"@type": "MyNewType1","@schemaLocation": "path_to_file#/definitions/MyType",
and
"@type": "MyNewType2","@schemaLocation": "path_to_file#/definitions/MyType",
(i.e.: multiple @type values for the same schema definition)
We can only have as in your example the, @type value being used as the identificador pointing a place within the @schemaLocation file, right?
"@type": "MyType","@schemaLocation": "path_to_file#/definitions/MyType",
------------------------------
Marcos Donato da Silva
Ericsson Inc.
Original Message:
Sent: Jul 20, 2020 12:37
From: Vance Shipley
Subject: Swagger and @schemaLocation
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",
------------------------------
Vance Shipley
SigScale
Original Message:
Sent: Jul 20, 2020 11:12
From: Marcos Donato da Silva
Subject: Swagger and @schemaLocation
Hello,
One additional question:
Is it legal to have one value pointed at @type and, a different one pointed at @schemaLocation or, should the value at
@type and @schemaLocation always coincide?
Example:
I have extended the Product Offering element by adding a new field to id: PO2PO relationship (that is not there on the TMF620).
So, this new model will have an extended @schemaLocation address: Let's say è ../ProductOfferingWithRelations.json
and a new @type: ProductOfferingWithRelations
Then, can I defined on top of this model two extra @type variants:?
Let's say one will be a PO to sell only phones on Red Color and another one to sell only phones on Black Color so that the first one will have
a fixed property/characteristicUse called "Red Color" and the second one a fixed property/ characteristicUse called "Black Color" (please, don't mind with the examples,
they're just illustrative – the objective here is simply to highlight that I have two predefined models (with different attribute values) based on the same data model
indicated by the @schemaLocation).
Can I have in this case two different @types: e.g: ProductOfferingWithRelationsRed and ProductOfferingWithRelationsBlack, both sharing the same
@schemaLocation: ProductOfferingWithRelations?
Thanks
Original Message:
Sent: 7/17/2020 1:40:00 AM
From: Vance Shipley
Subject: RE: Swagger and @schemaLocation
Your example isn't correct as it is not referencing a schema at all:
"@schemaLocation": "https://.../TMF645-ServiceQualification-v4.0.0.swagger_extended.json",
The correct syntax to provide a reference to the schema for RelatedParty2 would be:
"@schemaLocation": "https://.../TMF645-ServiceQualification-v4.0.0.swagger_extended.json#/definitions/RelatedPary2",
------------------------------
Vance Shipley
SigScale
------------------------------