Open APIs

Expand all | Collapse all

TMF639v4 Discrepancies between Guide and Swagger

  • 1.  TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 29, 2021 09:01

    Hey Community,

    We are currently evaluating the TMF639 OpenAPI and I noticed in one area that there is a difference between the associated User Guide and the Swagger specification.
    On p14 of the User Guide the sub-resource ResourceRelationship is described with the following fields

    • relationshipType = string
    • resource = ResourceRefOrValue
    On the other hand the Swagger TMF639v4 hold the following definition:

    • id = string
    • href = string
    • relationshipType = string
    • resourceRelationshipCharacterstic = Characteristic[]
    • (and the obvious '@type and so on....)

    Does anyone know about this mismatch? I personally would prefer a mixture of both :-)​

    "ResourceRelationship": {
            "type": "object",
            "properties": {
              "relationshipType": {
                "type": "string"
              },
              "resource": {
                "$ref": "#/definitions/ResourceRefOrValue"
                }
              },
              "resourceRelationshipCharacteristic": {
                "type": "array",
                "items": {
                  "$ref": "#/definitions/Characteristic"
                }
              },
              "@baseType": {
                "type": "string",
                "description": "When sub-classing, this defines the super-class"
              },
              "@schemaLocation": {
                "type": "string",
                "format": "uri",
                "description": "A URI to a JSON-Schema file that defines additional attributes and relationships"
              },
              "@type": {
                "type": "string",
                "description": "When sub-classing, this defines the sub-class entity name"
              }
            }
          }



    Thanks and greetings from Oldenburg,

    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------


  • 2.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 29, 2021 14:28
    Hi Jan
    The API tooling that is used to generate the swagger expands out RefOrValue by resolving the $allOf and inserting the $ref targets. In general, the Open API swagger files are completely self-contained​ with no unresolved references to other schemas.
    However the spec is generated from the original schemas without resolving the references, instead the referred schemas are quoted in the spec.
    Hope it helps

    ------------------------------
    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: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 30, 2021 01:49

    Hi @Jonathan Goldberg,

    Thanks for your reply. I understand how the various artifacts are created. Of course, the question remains which of the variants counts. There is definitely a difference that cannot be caused by dereferencing. If someone implements TMF639 according to Swagger, he will never pass the conformance check.

    Maybe @Stephen Harrop can jump in and answer this question? He seems to be the one who commited the latest Swagger to Github.

    Any help is much appreciated.
    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------



  • 4.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 30, 2021 05:07
    Not sure I understand the problem. The technical API contract is described by the swagger. The conformance test kit is eventually also derived from the swagger. What exactly is the difference that you refer to (barring defects in the tooling, which is always possible I suppose).

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



  • 5.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 30, 2021 05:30
    Edited by Jan Lemmermann Jul 30, 2021 05:31
    Ah that's easy to overlook. Let me give you folks a better example by posting an excerpt of the JSON-Payload.

    Resource entity based on TMF639 User Guide:
    {
      "id": "0815,
      "href": "/resource/0815",
      "resourceRelationship": [
       "resourceRelationshipType: "contains",
       "resource": {
         "id": "1234",
         "href": "/resource/1234",
         "@referredType": "Fan",
         "@type": "ResourceRefOrValue"
       }
      ],
      "@type: "FanSlot",
      "@baseType": "Resource"
    }​


    Resource entity based on TMF639 Swagger:
    {
      "id": "0815,
      "href": "/resource/0815",
      "resourceRelationship": [
       "resourceRelationshipType: "contains",
       "id": "1234",
       "href": "/resource/1234",
       "@type": "ResourceRefOrValue"
       }
      ],
      "@type: "FanSlot",
      "@baseType": "Resource"
    }​


    As you see there is a difference. The field resourceRelationship.resource is missing within the Swagger definition.

    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------



  • 6.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 30, 2021 09:25
    Jan - seconded, I was looking at the same point a few days ago.  The "resource" is critical, the relationship is meaningless without it.  It is a defect in the Swagger, though I can't comment on whether it originates in the tooling or elsewhere.

    ------------------------------
    Simon Durrant
    Amdocs Management Limited
    ------------------------------



  • 7.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 31, 2021 11:19

    Hi Jan,

    We (SATEC) have also experienced these discrepancies during the implementation of several APIs. For us the document always prevails over the swagger. As it is generated automatically, looks like sometimes there are inconsistencies with the formal definition of the API.

    Regards,
    Abel



    ------------------------------
    Abel Ruiz Huerta
    SATEC GROUP
    ------------------------------



  • 8.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Jul 31, 2021 11:19

    Hi Jan,

    We (SATEC) have also experienced these discrepancies during the implementation of several APIs. For us the document always prevails over the swagger. As it is generated automatically, looks like sometimes there are inconsistencies with the formal definition of the API.

    Regards.



    ------------------------------
    Abel Ruiz Huerta
    SATEC GROUP
    ------------------------------



  • 9.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Aug 01, 2021 08:56
    Hi all

    To me it looks like a publishing error. I've looked through my local copy of the Open API working environment, and I can't find any trace of this expanded resource relationship class (including characteristics on the resource in our schema files.
    The only thing I can think of is that the resource relationship class was edited and the swagger regenerated but the corresponding user guide was not regenerated. To investigate more fully would need deep delving into the GitHub repository.
    But from a functional perspective, the difference is as follows:
    • In the swagger, the id and href refer to the related resource - and the relationship has characteristics
    • In the user guide, the id and href are of the relationship itself, and the resource is embedded (as a reference or a value) - and the relationship has no characteristics
    It seems to me that the swagger is correct, there is no reason for the relationship class to have its own id and href, and the characteristics are missing (even though the corresponding resourcespecificationrelationship does have characteristic specs).

    Maybe @Ludovic Robert and @Vance Shipley and @Kamal Maghsoudlou have insights into this problem?​​​
    Anyway I've created this issue to record the defect: https://projects.tmforum.org/jira/browse/AP-2817 - if you are Open API project member you can see the Jira contents.

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



  • 10.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Aug 02, 2021 03:32
    Hi Jonathan,

    Having the "resource" attribute with a ResourceRefOrValue is critical to being able to build graphs of resources, as per depth and expand.  Using the id/href in the ResourceRelationship is not sufficient.  Losing this attribute is a significant loss of functionality compared with the previous version.  (It is also possible that the relationship itself has its own id.)

    Thanks,

    Simon.

    ------------------------------
    Simon Durrant
    Amdocs Management Limited
    ------------------------------



  • 11.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Aug 02, 2021 10:16

    I fail to see the problem. The schema you provided has a resource attribute. I'm looking at ResourceRelationship.schema.json in the (private) GitHub repo and it's there too. The generated swagger for TMF639 in the repo also has it. The User Guide is aligned.

    Is it just confusion about the presence of id and href in ResourceRelationship?  Those are there because at the bottom of the schema we have:

    "allOf": [
        {
            "$ref": "../Common/Entity.schema.json#Entity"
        }
    ]

    ... which makes it Addressable and Extensible.

    Aha, I see the problem now.  The ResourceRelationship schema in the swagger referenced in the Open API Portal has the bad form.



    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 12.  RE: TMF639v4 Discrepancies between Guide and Swagger

    TM Forum Member
    Posted Aug 02, 2021 11:40
    @Vance Shipley I'm glad that we are looking at the same Swagger file :-D

    If anyone is still having trouble finding the difference, feel free to post here. But it seems that I am not the only one, but just the first one who writes here about this defect. Thanks @Jonathan Goldberg for the Jira issue. I'll try to keep an eye one the ticket.
    ​​

    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------