Package Model

[mkaplun]

The proposed vision of SDCM's Model part aims to streamline and increase abstraction levels.

The following is the list of the proposed changes: Model Package

• [ ] Interface:

Adding Category attribute of type Taxonomy. Note: the SDCM here does not prescribe the specific taxonomy; it can be done in the future in the context of human or formal language documents.

• [ ] Operation:

Idempotency is removed as it is of little or no use. Synchronicity is replaced with Boolean 'synchronous'. Message Exchange Pattern is replaced with an attribute of type Enumeration (see Note for the Category attribute in the Interface class). Processing Consideration is removed as it is of little or no use.

• [ ] Message:

No changes at all.

• [ ] Fault:

The Fault class is an extension of the class Message and therefore inherits all Message attributes, but the value of attribute 'direction' is constant 'out'. (Assigning values to the attributes in the conceptual model may require further considerations.)

• [ ] Header:

The current classes Header and Header Fields are combined into one, similar to the approach applied to Profile classes. Every instance of the Header now represents a single header field related by one-to-many to the Message. Header attributes allow name-value pairs to be described optionally accompanied by brief descriptions.

• [ ] Payload:

The Payload Type is rendered as an attribute of type Enumeration, similar to the approach used in the Operation class. See also Note for Interface's Category.

• [ ] Data Entity:

Associated Data Definition class is replaced with the attribute 'source' of type Document that points to either the human or machine-processable document that defines the Data Entity (e.g., XML schema, data standard).

REST Package: The purpose of grouping REST-specific classes in a package is to show that they belong to a different family of classes while also demonstrating that they are parts of the Model (a kind of interface).

• [ ] Method:

The Method class is a specialization of the class Operation. It inherits all Operation's attributes with the only distinction that the value of 'name' in the Method must be one of the "HTTP methods" enumeration (not shown but described in the model.) Note: all classes are derived from "Service Description Conceptual Model (SDCM) Extension for REST-style Web Services"

• [ ] Resource:

Attribute 'id' is added. It could be either an absolute or relative URI of the Resource. It also, in some cases, may have the same value as the attribute 'path'.

• [ ] Parameter:

The enumeration 'type' is included as a class attribute.

• [ ] Representation:

No changes. However, it should be considered whether Representation information is redundant with the information provided by the attribute 'source' in the Data Entity class.

[wznira]

I like this approach. I just have a few questions -

1. Interface category. I assume this is to describe whether this is a method-oriented, message-oriented or resource-oriented interface.
2. Resource id. I think the id is the same as the path. A RESTful resource is identified by a URI, which SHOULD be dereferenceable. @mkaplun -- are you thinking about using path in case the id is not dereferenceable?
3. Fault. Suggest that we have a subclass of Fault for REST web services with a required field called "HTTP response code".

[caroluri]

I also like this simplification. One suggestion: instead of "Data Entity" , I suggest just calling it "Data". Data entity connotes a "data element", which in turn can connote a primitive element even though that's not its intent. Also, the NSRR also calls it "Data", and it doesn't seem to confuse people. One more thought: calling it "Data" would be similar to calling the message header "Header" instead of "Header Field".

[mkaplun]

The diagram has been modified with respect comments made on post.

• [x] The Data Entity class has been replaced by the Data class.
• [ ] Also note changes to association in 'REST Interface' package.
• [ ] The association between Resource and Representation may require more considerations.

[caroluri]

Looks good to me.

[mkaplun]

RE: @wznira message

1) The answer is 'yes.' However, the model now only says that the type is Taxonomy without specifying the taxonomy. That should allow us to modify or create a new taxonomy.

2) Agree. It seems logical that the id of Resource should match the path of Resource. The question is whether both attributes should be included in the Resource class or only one (since they are identical) and which one.

3) Agree. And there is a question similar to item 2). Every fault(error) message always has a unique id (error code). Apparently, we must consider adding an id to the fault code in the model. However, an "HTTP Response Code" is not always an error code; there are many other response codes. And this may suggest that we have to extend the Message class in the REST Interface Package by adding an attribute HTTP Response Code. Or, we can say that the 'HTTP Response Code' belongs to the Header class. It seems cleaner and frees us from making the model more complex.

[wznira]

2. Agree. It seems logical that the id of Resource should match the path of Resource. The question is whether both attributes should be included in the Resource class or only one (since they are identical) and which one.

If we have to choose between an id (a generic URI) and a path (a URL), I suggest we use the id, since the Model describes what the URI should be logically. In the case where an id does not match the path to a resource as deployed, this is likely due to constraints with the implementation -- which suggests that we may want to consider extending the Endpoint class in Grounding to have a REST Endpoint subclass? As stated below, this could make the model more complex, and I am not the added benefit warrants it.

3. Agree. And there is a question similar to item 2). Every fault(error) message always has a unique id (error code). Apparently, we must consider adding an id to the fault code in the model. However, an "HTTP Response Code" is not always an error code; there are many other response codes. And this may suggest that we have to extend the Message class in the REST Interface Package by adding an attribute HTTP Response Code. Or, we can say that the 'HTTP Response Code' belongs to the Header class. It seems cleaner and frees us from making the model more complex.

I agree that extending the Message class in the REST Interface package seems to be the cleanest solution. However, as @mkaplun pointed out, any clean solution would make this structure more complex. Though, I do not think HTTP Response Code belongs to the Header class