Modelling of operation parameters

[mjacoby]

Image the following scenario: We have an operation called doStuff which takes a single input parameter called data. data is a SubmodelElementList of SubmodelElementCollections with a predefined structure, i.e. Property x of type string, Property y of type integer, and Property z of type boolean.

An example invocation call with valueOnly serialization would look like this

{
    "inputArguments":
    {

        "data": [
            {
                "x": "value1",
                "y": 0,
                "z": true
            },
            {
                "x": "value2",
                "y": 1,
                "z": false
            },
            ...
        ]
    },
    "inoutputArguments": {},
    "clientTimeoutDuration": "PT60S"
}

How should the operation be modeled to reflect this? If I model the data input parameter as a list with one element to describe the structure of the SubmodelElementCollection that is expected like this...

{
    "modelType": "Operation",
    "idShort": "doStuff"
    "inputVariables": [
        {
            "value":
            {
                "modelType": "SubmodelElementList",
                "idShort": "data",
                "orderRelevant": true,
                "typeValueListElement": "SubmodelElementCollection",
                "value": [
                    {
                        "modelType": "SubmodelElementCollection",
                        "value": [
                            {
                                "modelType": "Property",
                                "idShort": "x",
                                "valueType": "xs:string"
                            },
                            {
                                "modelType": "Property",
                                "idShort": "y",
                                "valueType": "xs:integer"
                            },
                            {
                                "modelType": "Property",
                                "idShort": "z",
                                "valueType": "xs:boolean"
                            },
                        ]
                    }
                ]
            }
        }
    ],
    "outputVariables": []
}

... then this reads like data only accepts exactly one element instead of an arbitrary number. If you argue that this should mean that data contains an arbitrary number of elements than how is it possible to define that it should contain exactly one element?

I was looking at Part 1 of the AAS specification to find an answer but unfortunately without success.

My initial thought was that setting the kind property on the SubmodelElementCollection to template might be the answer, but this property has been marked as deprecated sin v3.0.

Using Qualifiers also came to mind but it seems TemplateQualifiers are only allowed on elements that belong to a Submodel of kind=template (which is not the case here is this Submodel is an instance) according to Constraint AASd-129

If any Qualifier/kind value of a Qualifiable/qualifier is equal to TemplateQualifier and the qualified element inherits from "hasKind", the qualified element shall be of kind Template (HasKind/kind = "Template").

To me, it seems like I am therefore not able to properly model/describe the input parameters of my operation which means nobody can use my AAS/operation without an accompanying document describing how to use it. Am I missing something? Is there a way to describe this?

[JoergNeidig]

Thank you for your request. We will discuss this in the working group. I do want to make the point, however, that the SME operation lets you model the interface of a technical operation. This is similiar to a simple function signature with function name, arguments, return types. We are aware that using an operation is a lot more complicated than that and things for a full semantic model like timing, synchronous/asynchronous, internal states, relation to other operations, etc. are not described here.

[mjacoby]

I am looking forward to the feedback from the working group.

This is similiar to a simple function signature with function name, arguments, return types

I want to highlight that my question is exactly about the argument and return types and nothing more. To rephrase my initial question: how to model an input argument of type SubmodelElementList that can only contain elements of type SubmodelElementCollection with a given structure? This could theoretically be done adding one SubmodelElementCollection with the desired structure to the list...however the semantic that this means a list can contain any number of such SubmodelElementCollections is not defined anywhere and if it would be defined like this, how could then the case where we want the list to only contain exactly one such element look like? Or is this something that cannot be modelled (a list with a fixed number of elements)?

This unclear/missing semantics are also the reason I have labelled this as a bug, because right now, nobody can implement and use the specification, at least with this regard, because it is underdefined.

[alexgordtop]

2024-09-04 - TF Part 1 of AAS Working Group: The attribute "semanticIdListElement" of SubmodelElementList is meant to document the kind of SME, that should be used. The number of SME inside the SML is either part of the semantic description or could describe in your SubmodelTemplate.

We do not consider this as a bug. But feel free to raise a new issue and make a concrete proposal how to extend the specification.

Please feel free to to re-open the issue if did not answer your question.

[mjacoby]

The attribute "semanticIdListElement" of SubmodelElementList is meant to document the kind of SME, that should be used.

This would mean defining an operation that takes a list of elements each with the same fixed set of properties as described in the example above would not be possible with only knowledge about the AAS meta model but would require to know and understand a certain proprietary semanticId, right?

This seems not useful at all in practice. To my understanding, the meta model should enable anybody who knows the AAS meta model to invoke any operation. If however in such a case additional knowledge about a semanticId would be required most consumers of an AAS would no longer be able to call most of the operations. To me, that sounds like a major design flaw and not what anybody would expect.

Furthermore, semanticId should only contain additional/optional semantic information but not information required to interact with an AAS, e.g., it would be ok for a semanticId to hold the information which unit of measurement a property is in or to provide additional insights about what the operation is doing exactly but not for essential information like the name of a property or, in the above example, a structure of a SubmodelElementCollection.

Following your approach it should also be ok to not describe any input arguments at all and just put a semanticId on the operation itself which "says" that this operation has input arguments a, b, and c. To me, that does not make any sense at all, because then why have a formal description of input arguments at all if it is not reliable or only understandable/usable with additional knowledge that is outside of the AAS specification?

The number of SME inside the SML is either part of the semantic description or could describe in your SubmodelTemplate.

Is there any information/documentation how this can be achieved using a SubmodelTemplate? Also, such a basic thing as describing the arguments of an operation should not require the use of a SubmodelTemplate. In fact, this feels like misusing the concept of SubmodelTemplate (SMT) because why should one create a SMT for a submodel that (potentially) is only used exactly once? This is not only counter-intuitive and overly complex but also misusing the concept of SMT.

It would be very helpful if someone could provide me with a concrete proposal how to model the exact thing it presented in the example.

@alexgordtop Unfortunately, I do not have sufficient rights to re-open this issue. Would it be possible for you to please re-open it instead?

[alexgordtop]

@mjacoby Sorry, I don't have the right, too.

@BirgitBoss Could you reopen it?