search

faa-swim / sdcm

Issues tracking for Service Description Conceptural Model
1 stars 0 forks source link

Possible inconsistency between SDCM 3.0 and OpenAPI Specification v.3.1 (Swagger) #18

Open mkaplun opened 1 year ago

mkaplun commented 1 year ago

According to Swagger's specification:

"For each path, you define operations (HTTP methods) that can be used to access that path. ... A single path can support multiple operations, for example, GET /users to get a list of users and POST /users to add a new user. OpenAPI defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed – even if they have different parameters (parameters have no effect on uniqueness)."

In SDCM 3.0, the class Resource is not associated with the class Operation. It also includes the non-defining attribute path, which has no relevance to the uniqueness of the Operation.

  1. Is SDCM 3.0 can be interpreted in a way that is consistent with Swagger's architecture?
  2. If not, should the UML be changed? If yes, then how? E.g., add association class?
  3. Or is it best to keep the current SDCM as it is for potential future interpretations or extensions at either logical or physical levels?
wznira commented 1 year ago

In SDCM 3.0, the class Resource is not associated with the class Operation. It also includes the non-defining attribute path, which has no relevance to the uniqueness of the Operation.

  1. Is SDCM 3.0 can be interpreted in a way that is consistent with Swagger's architecture?

I do see an inconsistency.

I think the SDCM Resource class can be considered equivalent to the Swagger Paths object. The path attribute in the Resource can be consistent a "natural key" for the Resource object (to borrow a database term).

The potential issue is the association between Resource and Message. I think Request Body and Response objects in the Swagger can be considered equivalent to the SDCM Message classes. As @mkaplun pointed out, in Swagger, the requests/responses are identified by the composite key - path and http-method.

  1. If not, should the UML be changed? If yes, then how? E.g., add association class?

I think this would be a major change. For example, we have not been distinguishing Request and Response messages in SDCM. For GET requests, there should be no request body but for POST and PUT there should be. See #3 below.

  1. Or is it best to keep the current SDCM as it is for potential future interpretations or extensions at either logical or physical levels?

I suggest that we keep SDCM as is and maybe add a note (Did @caroluri use to call it "Erratta"?).

wznira commented 1 year ago

One proposed solution for issue #17, the "OperationalResource" class in particular, could offer a possible way to align the SDCM structures with Swagger, if we decide to go that way.

mkaplun commented 12 months ago

Based on the discussion on this issue, it can be concluded that the following statements are true:

  1. An Operation is performed on a Resource.
  2. A Resource is uniquely identified by a combination of its path and the name of one of the HTTP methods used to manipulate it.
  3. The UML association from Operation class to Resource class, labeled "manipulates", should be sufficient to show this relationship in a UML diagram.