Clarify Non-Applicability of SerializationModifiers

[otto-ifak]

In Section 11.3 "Applicability of SerializationModifiers" it is not specified what Applicability means in the context of HTTP/REST.
Especially non-applicability is not specified.

Which one holds:

• A modifier is not applicable means that it may not be passed as parameter. Doing so must result in an error
• A modifier is not applicable means that it may be passed but will be ignored.

I would argue that the second option would be better.
Main reason for this, is that for Level the default is deep which is "not applicable" in most contexts.

[sebbader-sap]

As discussed in the task force meeting today, we need one or two more iterations.

One potential option is to extend proposal from you, @otto-ifak, a little bit by stating that a server should not throw any error for not applicable query parameters, however, for content modifiers the not applicable ones have to result in an error, usually 404.

In any case:

• Add a note to the specification in the HTTP section.

[mjacoby]

As the issue seems a bit more complex than initially though I am trying to highlight the problem in more detail

Section 11.3 "Applicability of SerializationModifiers" contains the following table

What "applicability" means here in terms of REST API is unclear. As different modifiers (level, content, extent) are mapped to URLs differently, we need to distinguish them.
As the content modifier is mapped as a part of the actual URL, it would be intuitive to assume "not applicable" here means the URL simply does not exist. However, things are more complex as in the AP we only have a single call /submodels/{submodelId}/submodel-elements/{idShortPath} to access any kind of submodel element. However, according to the table, they shall be treated differently, e.g. for Operation content modifier value is not allowed.

As the call to /submodels/{submodelId}/submodel-elements/{idShortPath}/$value obviously must be allowed as it is valid for some types of submodel elements such as Property that the only logic thing to do is to return 400 Bad Request when executing this with an idShortPath pointing to a type of submodel element that is not supported according to this table.

This seems somewhat inconsistent with e.g. /shells/{aasId}/$value not being available at all and therefore returning 404 Resource not found. This illustrates how there is no clear and consistent definition of "(non-)applicability".

For level and extent modifier the behavior is different as before as they are not serialized as part of the URL but as query string parameters. What does "(non-)applicability" mean in this context?

• that the modifiers are not allowed to be used at all, i.e., when they are used 400 Bad Request should be returned?
• that the modifiers are ignored as if they were not present?

This is where we are back at the original post.

Thinking towards a solution...

• level modifier is not a problem as for those elements where it is not applicable, both deep and core would return exactly the same result as the elements do not have children.
• this is the same for the extent modifier
• content modifier is well-defined for all types except submodel element in that case that the corresponding URLs are not part of the REST API as stated in the corresponding OpenAPI/Swagger document

This leaves only the following questions: What is the expected behavior when calling ...

1. /submodels/{submodelId}/submodel-elements/{idShortPath}/${content-modifier} with a content modifier that is not applicable for the underlying element type?

• Suggestion: return 400 Bad Request
• Implications: no changes to Swagger required, add explicit explanation to specification in REST API section

2. /submodels/{submodelId}/submodel-elements/{idShortPath}?{modifier}={modifier value} with a level or extent modifier that is not applicable for the underlying element type?

• Suggestion: "ignore", or to phrase it more clearly, apply these modifiers but as they do not have any effect the result is the same as ignoring them
• Implications: no changes to Swagger required, add explicit explanation to specification in REST API section

3. any URL related the elements different than submodel element with a level or extent modifier that is not applicable, e.g. /shells/{aasId}?level=deep?

• Suggestion: "ignore", or to phrase it more clearly, apply these modifiers but as they do not have any effect the result is the same as ignoring them
• Implications: changes to Swagger required as these query parameters are currently not allowed