Open APIs

 View Only

TMF638 ServiceRefOrValue entity definition

  • 1.  TMF638 ServiceRefOrValue entity definition

    Posted May 11, 2023 08:17

    Hello dear experts,

    In the TMF638, there is a ServiceRefOrValue entity which is used when defining supporting services as well as relationships of the service with other services. i.e. in the definition of ServiceRelationship, service is defined as:

    "service": {
    	"$ref": "#/definitions/ServiceRefOrValue"

    In the definition of the ServiceRefOrValue entity in the swagger file it states that Id parameter is required, which is in contrast with TMF630_REST_API_Design_Guidelines_Part_2_v4.0.0 which states following:

    For EntityRefOrValue all attributes are optional.
    If it is a Ref, id and href are mandatory but if it is Value then only the mandatory parameters from the Entity referenced are required (id and href can be also added if the reference is used to modify the contents of an existing entity). 

    Additionally it states:

    In Swagger implementation :
    • Swagger 2.0 we should allow for a less strongly type solution. We will create the swagger schema as if it was a value and it will be up to the implementation to implement ref or value. All the parameters in the value class should be optional.

    • In Swagger 3.0 we SHOULD make use of oneOf between value class and ref class.

    Which makes perfect sense.

    In the document example, a service is created with the relationship where related service is specified through a Ref:

    "serviceRelationship": [{
    		"relationshipType": "DependentOn",
    		"service": {
    			"href": "",
    			"id": "5645",
    			"@type": "ServiceRef",
    			"@referredType": "Service"

    So if we wanted to add a relationship to a service via Value, it wouldn't be possible since Id parameter is required.

    I've also checked other examples and in most cases Id is not required in EntityRefOrValue entities.

    My question is whether this is by design or is this a mistake in swagger spec.

    Thanks a lot!

    Nebojsa Peric