De-Serialization of API parameter "assetIds"

[in-fke]

First of all, there seems to be a discrepancy between the prose spec of the API parameter "assetIds" and the OpenAPI Spec.

Prose Spec
https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf
states
Pages 114/115

When retrieving AssetAdministrationShells (/shells, /lookup/shells), a query parameter “?assetids=” can be specified. Such assetId may be a globalAssetId or specificAssetId. The corresponding keyvalue-pair is first serialized to JSON and then base64url-encoded. The resulting encoded string is the value of “?assetids=”.
…
This encoding (serialize to JSON + base64url) is also used for SpecificAssetIds, i.e. for GetAllAssetAdministrationShellIdsByAssetLink (/lookup/shells). For the example “[{"key": "globalAssetId","value": http://example.company/myAsset},{"key": "myOwnInternalAssetId","value": "12345ABC"}]”, the resulting base64url-encoded value of the query parameter is “?assetIds=W3sia2V5IjogImdsb2JhbEFzc2V0SWQiLCJ2YWx1ZSI6ICJodHRwOi8vZXhhbXBsZS5jb21wYW55L215QXNzZXQifSx7ImtleSI6ICJteU93bkludGVybmFsQXNzZXRJZCIsInZhbHVlIjogIjEyMzQ1QUJDIn1d”.

According to this spec, it's a single value.

OpenAPI Spec
According to https://app.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetIds
The parameter is an array

A list of specific Asset identifiers. Each Asset identifier is a base64-url-encoded [SpecificAssetId]

To sum up:

1. in prose, it's either an array of SpecificAssetId or a single SpecificAssetId, json-rendered and base64 encoded to a single value
2. in YAML, it's an array of strings, each string resulting from a json-rendered, then base64 encoded SpecificAssetId

Also.

The server-side binding
https://github.com/eclipse-basyx/basyx-java-server-sdk/blob/main/basyx.aasrepository/basyx.aasrepository-http/src/main/java/org/eclipse/digitaltwin/basyx/aasrepository/http/AasRepositoryApiHTTPController.java#L101

public ResponseEntity<PagedResult> getAllAssetAdministrationShells(@Valid List<SpecificAssetID> assetIds, @Valid String idShort, @Min(1) @Valid Integer limit, @Valid String cursor)
would seem to imply that the OpenAPI spec is correct, but I don't see where it would be doing the Base64 decoding.
Depending on which spec is correct, the signature would have to be
List<String> encodedAssetIds
or
String encodedAssetIds
And they would need to be base64 decoded and then json-de-serialized.

All in all the "assetIds" parameter seems flawed with all this base64 encoding, also see admin-shell-io/aas-specs-api#19

[FrankSchnicke]

The example [{"key": "globalAssetId","value": http://example.company/myAsset},{"key": "myOwnInternalAssetId","value": "12345ABC"}] includes multiple assetIds. "globalAssetId" is a reserved name indicating that the globalAssetId should be checked (cf. Part 2, p. 75, Description of assetIds input parameter). The rest are the specificAssetIds where key corresponds to the name and value corresponds to the value (cf. Part 1, p. 61) .

Thus, the Spec should be in line with the OpenAPI specification in this regard. However, the getAllAssetAdministrationShells function should take List<Map<String, String>>.