This looks okay to me.
"relatedParty": [
{
"id": "string",
"href": "string",
"name": "string",
"role": "string",
"extendedRole" : "string", "@baseType": "RelatedParty",
"@schemaLocation": "https://.../TMF645-ServiceQualification-v4.0.0.swagger_extended.json",
"@type": "RelatedParty2",
"@referredType": "string"
}
]
Please note for another case where schema has to be retrieved to understand the extension. Please have a look a characteristic which is an object instead of a usual data type. In that case, you will not be able to expand on the main swagger.
------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.
------------------------------
Original Message:
Sent: Jul 16, 2020 07:10
From: Fethi Ben Bagdad
Subject: Swagger and @schemaLocation
Hi Varun,
I don't think I was clear enough.
When I say "modify the original swagger", I don't want to modify the base type but add my custom object in the original file in order to have a direct view on this object via the swagger.
Take the example on the "RelatedParty" object that I would like to extend to "RelatedParty2" in the ServiceQualification API for example, here is what the swagger will mention after modifying the json file:
- RelatedParty : is the base type of the TMF standard object
- RelatedParty2 : is the base type of the TMF standard object + custom attributes
The implementation is "fairly" simple and allows the consumer to have a direct view of the custom objects.
While the alternative of using schemalocation would give us something like this:
"relatedParty": [ { "id": "string", "href": "string", "name": "string", "role": "string", "@baseType": "RelatedParty", "@schemaLocation": "https://.../TMF645-ServiceQualification-v4.0.0.swagger_extended.json", "@type": "RelatedParty2", "@referredType": "string" } ]
In this case, the swagger will not mention the "RelatedParty2" directly, the consumer needs to access to the schemalocation to retrieve the model "RelatedParty2".
What is the recommandation regarding the developpment of extended TMF object ?
I hope I have been clear enough :)
Regards,
Fethi
------------------------------
Fethi Ben Bagdad
VOO SA
Original Message:
Sent: Jul 15, 2020 21:02
From: Varun Nair
Subject: Swagger and @schemaLocation
When you say change the original swagger, are you trying to flatten the structure?
For e.g. If you want to extend a ServiceCharacteristic with schema object, how will you flatten without deviating from TMF object model?
------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.
Original Message:
Sent: Jul 15, 2020 05:53
From: Fethi Ben Bagdad
Subject: Swagger and @schemaLocation
Thanks for your feedback Varun & Vance.
What is your recommendation regarding the original swagger ?
- Change the original swagger: Makes the maintenance more complex but simplifies the implementation
- Use a different JSON: makes the implementation more complex but simplifies the maintenance
Thanks again
Regards,
Fethi
------------------------------
Fethi Ben Bagdad
VOO SA
Original Message:
Sent: Jul 15, 2020 03:11
From: Vance Shipley
Subject: Swagger and @schemaLocation
We should add some (normative) clarity around this in TMF630 but I would argue that the @schemaLocation value identifies the namespace of the schema. It need not be a link which serves the content. I would cite the JSON Schema Core specification:
8.2.2. The "$id" Keyword
The "$id" keyword identifies a schema resource with its canonical URI.
Note that this URI is an identifier and not necessarily a network locator. In the case of a network-addressable URL, a schema need not be downloadable from its canonical URI.
A canonical link is described in RFC6596.
------------------------------
Vance Shipley
SigScale
Original Message:
Sent: Jul 15, 2020 02:30
From: Varun Nair
Subject: Swagger and @schemaLocation
If I understood your query correct,
What are the guidelines about the use of a customer schemaLocation regarding the TMF Compliance ?
- The consumer should always check the schemaLocation on-the-fly to retrieve the custom objects/attributes ? Yes, the schema needs to be accessed run time from the schemalocation. If the schema is designed in JSON, it would be easy to read and will be consistent.
- The provider should provide a swagger wich contain the extended schemaLocation ? Yes. JSON with the schema definition should be available in schema location.
------------------------------
Varun Nair
Telstra Corporation
Note: This is an opinion based on my research and not an official TMF response.
Original Message:
Sent: Jul 14, 2020 05:31
From: Fethi Ben Bagdad
Subject: Swagger and @schemaLocation
Hi everyone,
We are currently having some questions about this.
Can you tell me how you see the way the consumer will know this "extended" object as it is not present in the swagger?
What are the guidelines about the use of a customer schemaLocation regarding the TMF Compliance ?
- The consumer should always check the schemaLocation on-the-fly to retrieve the custom objects/attributes ?
- The provider should provide a swagger wich contain the extended schemaLocation ?
Thanks in advance.
------------------------------
Fethi Ben Bagdad
VOO SA
Original Message:
Sent: Jun 24, 2020 00:56
From: Jonathan Goldberg
Subject: Swagger and @schemaLocation
Hi Marcos
The Open API standard does not prescribe the format of the file/stream referred to in @schemaLocation . Our examples generally refer to json schema, which is what we are using anyway in the Open API data model. But you could use any acceptable schema.
Actually swagger would not be relevant since swagger is an API definition format (which admittedly includes data structure schema elements).
Hope it helps
P.S. If you didn't do this already, suggest you synch up with your Ericsson colleague @Kamal Maghsoudlou regarding TMF620 - Kamal is very active in the open API team and was the "father" of the catalog APIs (including TMF620, although I am the current owner of that API).
------------------------------
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 23, 2020 10:59
From: Marcos Donato da Silva
Subject: Swagger and @schemaLocation
Hello,
I have a simple question:
Is it mandatory to use Swagger to generate the schemas for extended resources pointed by the @schemaLocation?
e.g.: I'm implementing TMF620 and, I want to extend the Product Offering (PO) model presented originally in the specification.
Therefore, I'll be using @baseType (to point to the original TMF PO version), @type (to indicate the name of the extended
element) and, @schemaLocation to point the actual schema of the extended version.
The questino is around the format of the file presented under @schemaLocation: Is it mandatory to have it in swagger format
or any other json schema notation can be used?
Thanks.
------------------------------
Marcos Donato da Silva
Ericsson Inc.
------------------------------