Open APIs

 View Only
Expand all | Collapse all

Swagger and @schemaLocation

  • 1.  Swagger and @schemaLocation

    TM Forum Member
    Posted Jun 23, 2020 10:59
    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.
    ------------------------------


  • 2.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jun 24, 2020 00:56
    Edited by Jonathan Goldberg Jun 24, 2020 00:59
    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.
    ------------------------------



  • 3.  RE: Swagger and @schemaLocation

    Posted Jul 14, 2020 05:32
    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
    ------------------------------



  • 4.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 15, 2020 02:31
    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.
    ------------------------------



  • 5.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 15, 2020 03:12
    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
    ------------------------------



  • 6.  RE: Swagger and @schemaLocation

    Posted Jul 15, 2020 05:53
    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
    ------------------------------



  • 7.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 15, 2020 21:03
    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.
    ------------------------------



  • 8.  RE: Swagger and @schemaLocation

    Posted Jul 16, 2020 07:10
    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
    ------------------------------



  • 9.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 16, 2020 19:39
    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.
    ------------------------------



  • 10.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 17, 2020 01:40
    Edited by Vance Shipley Jul 17, 2020 01:49
    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
    ------------------------------


  • 11.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 20, 2020 11:12

    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

     






  • 12.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 20, 2020 12:38
    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
    ------------------------------



  • 13.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 20, 2020 13:52

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



  • 14.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 20, 2020 19:10
    Hi Marcos,
    Are you looking for creating two instances of the same schema MyType or your requirement is to extend the MyType with a different set of attributes to define the MyNewType1 and MyNewType2?

    ------------------------------
    Varun Nair
    Telstra Corporation
    Note: This is an opinion based on my research and not an official TMF response.
    ------------------------------



  • 15.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 21, 2020 00:27
    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
    ------------------------------



  • 16.  RE: Swagger and @schemaLocation

    TM Forum Member
    Posted Jul 21, 2020 12:57
    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.
    ------------------------------