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?

[mjacoby]

The issue has been discussed in the Task Force "Interoperability of Implementations" and there is an agreement that the modelling of complex parameters is an essential aspects of operations that needs to be standardized.

To provide another perspective, let's look on how this operation would be defined in a programming language, e.g. in Java

class Coordinate {
   String x;
   int y;
   boolean z;
}

public void doStuff(List<Coordinate> data) {
  ...
}

This makes it quite obvious that the AAS meta model is missing a way to define custom-typed lists like List<MyCustomType>. The only thing close to this then AAS meta model currently offers is to create a list with a "template" instance of an element in it like this

{
    "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"
                },
            ]
        }
    ]
}

The property semanticIdListElement as described by @alexgordtop is not the solution here as it can only reference "static" types (i.e. types defined in the AAS meta model) but not custom/"dynamic" types and therefore is not restrictive enough. The equivalent in the Java example would be something like List<Object>.

The solution probably is to add some Qualifier(s) to either the SubmodelElementList or the SubmodelElementCollection (or both) specifying that the list can contain any number of collections with the exact same structure as the one provided.
I think something similar is already used describing allowed cardinality in submodel templates. This probably can be re-used.
I am aware, that it is already possible to just use these but it is important for interoperability issues that these must be standardized and described in meta model so that everyone knows their meaning and can use the operation.

[BirgitBoss]

The property semanticIdListElement as described by @alexgordtop is not the solution here as it can only reference "static" types (i.e. types defined in the AAS meta model) but not custom/"dynamic" types and therefore is not restrictive enough. The equivalent in the Java example would be something like List<Object>.

semanticIdListElement is a semanticId and what you would need to do for a customer defined type is to define a unique semanticId for it, e.g.
https://myexamplecompany.com/myNewDataTypeForOperationParameter

The complete Collection can be defined so it is clear how the operation parameter is looking like (in former versions of the metamodel it had kind=Template, now this is only implicitly like this because SubmodelElements do not inherit from "HasKind" any longer)

SubmodelElementList has the semantics that all elements within have the same structure (because they have the same semanticId). At least so far we do not support polymorphism. Only if you would like to specify that at least one elements needs to be specified or at most 5 etc. then you would need qualifiers, same as in Submodel Templates.

The qualifiers used in Submodel Templates are not part of the metamodel (this would be a separate issue). But for this issue: since there is a semanticId and hopefully a Submodel Template used for the creation of the Submodel with kind=Instance it is clear whether there are further restrictions to be followed when implementing it or not. Only if you have neither a semanticId nor a submodel template you could not further restrict it: it would be 0..*

So I do not see that there is any difference for lists compared to any other operation parameters.

[mjacoby]

I get what you are saying, i.e., that semanticId (resp semanticIdListElement) can be used to describe this.

However, this approach is inadequate as it would be proprietary. Operations are a basic and essential concept of Digital Twin and therefore any should be defined in the AAS specification without the requirement of using any SMTs or custom semantics.
Also, please remember that SMTs are optional, i.e., the AAS specification should be useful and fully usable (at last the basic concepts) without SMTs.

What would be the harm in, e.g., adding a qualifier for specifying multiplicity to the AAS specification?
This issue seems to be fundamental and easy to fix, so why not do it?