Wrong cardinality for output parameter 'payload' in operation GetAllSubmodelDescriptors

[mjacoby]

What?

AAS Part 2 v3.0 (IDTA Number 01002-3-0), Section 6.3.2 (page 52) defines operation GetAllSubmodelDescriptors with output parameter payload with cardinality 1.. but should ne 0.. as it could happen that there is no matching SubmodelDescriptor in the registry.

[BirgitBoss]

The payload is optional, this means if there are not Submodel Descriptors a corresponding error message is returned but no empty list, probably "SuccessNoContent" So my understanding is that the specification is correct.

[mjacoby]

I understand your train of thought, however there are some issues. SuccessNoContent is not an error code but, as the name suggests, an return code indicating that an operation has successfully been executed but does not have a result. Mapping things to the REST API, it would technically be ok to return 204 No Content with an empty body when there is no result. Although technically possible, the best practice for REST APIs does not do this but returns just an empty array. Personally, I have never seen any REST API return 204 instead of an empty array, so at least it will be unexpected behavior for anyone using the AAS API. The specification also never specifies that SuccessNoContent should/must be returned. In fact, the Swagger definition does not allow to return 204 No Content.

I also did some deeper digging/analysis to cross-check how this done for other GetAll calls and I did notice that there is some level of inconsistency. Basically, there are two "types" how the return value of those operations is defined

1. with cardinality 0..* and mandatory=true
2. with cardinality 1..* and mandatory=false

To me, this seems inconsistent and should be harmonized. I also noticed the following things during the analysis

• Operation AAS Repository#GetAllAssetAdministrationShells has output cardinality of exactly 1 while it should allow a list to be returned
• Operation AAS Repository#GetAllAssetAdministrationShellsByIdShort has output cardinality of exactly 1 while it should allow a list to be returned
• Operation Submodel Repository#GetAllSubmodelsBySupplementalSemanticId is defined in the overview table of the interface but detailed description defining its in-/output parameter is missing completely
• Operation AAS Basic Discovery#GetAllAssetAdministrationShellIdsByAssetLink has cardinality 1..* and mandatory=true - a unique combination that does not make sense
• Descriptions of the output parameter is quite inconsistent, sometime saying list of ... and sometime request ....s

To better understand the issues I am adding a table of all GetAll... methods in the specification

Interface	Operation	Cardinality	Mandatory	Output argument description text
AAS	GetAllSubmodelReferences	0..*	yes	Requested Submodel References
Submodel	GetAllSubmodelElements	0..*	yes	Requested submodel elements
AASX File Server	GetAllAASXPackageIds	0..*	yes	Matching package list; the PackageDescription includes all Asset Administration Shell identifiers, also those which may have not been requested through the aasId input parameter
AAS Registry	GetAllAssetAdministrationShellDescriptors	1..*	no	List of Asset Administration Shell Descriptors
Submodel Registry	GetAllSubmodelDescriptors	1..*	no	List of requested submodel descriptors
AAS Repository	GetAllAssetAdministrationShells	1	no	List of Asset Administration Shells
AAS Repository	GetAllAssetAdministrationShellsByAssetId	1..*	no	Requested Asset Administration Shells
AAS Repository	GetAllAssetAdministrationShellsByIdShort	1	no	Requested Asset Administration Shells
Submodel Repository	GetAllSubmodels	1..*	no	List of submodels
Submodel Repository	GetAllSubmodelsBySemanticId	1..*	no	Request Submodels
Submodel Repository	GetAllSubmodelsBySupplementalSemanticId	Missing!
Submodel Repository	GetAllSubmodelsByIdShort	1..*	no	Requested Submodels
CD Repository	GetAllConceptDescriptions	1..*	no	List of Concept Descriptions
CD Repository	GetAllConceptDescriptionsByIdShort	1..*	no	Requested Concept Descriptions
CD Repository	GetAllConceptDescriptionsByIsCaseOf	1..*	no	Requested Concept Descriptions
CD Repository	GetAllConceptDescriptionsByDataSpecificationReference	1..*	no	Requested Concept Descriptions
AAS Basic Discovery	GetAllAssetAdministrationShellIdsByAssetLink	1..*	yes	Identifiers of all Asset Administration Shells which contain all asset identifier key-value-pairs in their asset information, i.e. AND-match of key-value-pairs per Asset Administration Shell
AAS Basic Discovery	GetAllAssetLinksById	1..*	no	Requested asset identifier, which could be the globalAssetId or specificAssetIds.

In my opinion, there should only be one way to interact with such collections and in the REST API world this is typically returning 0..* (mandatory: yes) which is simply left empty when there are no (matching) results.