admin-shell-io / aas-specs-api

Repository of the Asset Administration Shell Specification DTA-01002 API

This is the repository for the AAS API Definitions

This repository contains specifications of the Asset Administration Shell APIs, including in particular the normative OpenAPI files of the AAS HTTP/REST API. These API descriptions are derived from the document series, part 2, "Specification of the Asset Administration Shell - Part 2" published by the IDTA.

Content

This repository provides the OpenAPI files published in the SwaggerHub organization Plattform_i40. All published SwaggerHub APIs are synchronized all the time with the respective folders in this repository using the GitHub Integration feature. In particular, the following APIs are contained:

API SPEC	GitHub	SwaggerHub
Entire-API-Collection API	Link	Link
Asset Administration Shell Registry Service Specification	Link	Link
Asset Administration Shell Repository Service Specification	Link	Link
Asset Administration Shell Service Specification	Link	Link
Submodel Registry Service Specification	Link	Link
Submodel Repository Service Specification	Link	Link
Submodel Service Specification	Link	Link
Discovery Service Specification API	Link	Link
Concept Description Repository Service Specification	Link	Link
Aasx-File-Server Service Specification	Link	Link

The following domains are synchronized manually as domain synchronization is not yet available in SwaggerHub:

API SPEC	GitHub	SwaggerHub
Part1-MetaModel-Schemas Domain	Link	Link
Part2-API-Schemas Domain	Link	Link
DINSPEC16593-Schemas Domain (Deprecated)	Link	Link

API Versions in GitHub Branches

The main branch contains the latest released version of all APIs and Domains. Current and previously released states are tagged with the corresponding release version in this repository, and marked with the Published tag in SwaggerHub. Working versions may be marked as private in SwaggerHub and therfore may not be visible to the public audience yet. In this repository, working versions appear as branches named after the target release version.
Note: In order to synchronize with the same GitHub branch, all versions should follow the exact same pattern.

Releases

The following versioning scheme is applied for release tags: 'V<major>.<minor>.<patch>'. Major versions indicate breaking changes while minor updates are backward compatible. The patch position is increased whenever bugfixes need to be applied. The following release contains the latest version of the AAS schemas (see also the releases section of this repository):

• 3.0.1 is the corresponding release for the V3.0.1 version of the AAS APIs, containing the normative schemas for the published document "Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces - Version 3.0.1". Use this release if you want to work with the latest specified AAS version.

Previous releases (deprecated by 3.0.1):

• 3.0 is the first major release for the AAS APIs, containing the normative API descriptions for the published document "Specification of the Asset Administration Shell - Part 2: Application Programming Interfaces - Version 3.0".

Contributing

Feature requests, reports about inconsistencies, mistakes etc. are highly welcome! Please submit a new issue.

If you want to contribute, see CONTRIBUTING.md.

SwaggerHub GitHub Synchronization

SwaggerHub requires a GitHub Access Token with repo permissions. It is good practice that the selected token has a defined expiration date. Therefore, at some point in time when the current token expires, the synchronization will fail and a new token needs to be added through the IDTA repository management team.

aas-specs-api's Issues

Rename mimeType to contentType

What?

Section: 9.4.2
Finding: Example of BLOB‘s ValueOnly-Serialization in JSON
Current: mimeType

How?

Suggestion: contentType (as per Part 1)

Return Type of /lookup Interface

What?

Why do you only get identifier objects back? What do you do next with these IDs, which endpoint do you call with them and how do you know it?

How?

The descriptor is the better return type because it can be used to convey the endpoint of the aas or submodel.

This issue relates to finding IPA#5.

Applicability of Output Modifiers for ReferenceElement

What?

Section: 9.3 & 10.5
Finding: A „ReferenceElement“ NOT mentioned in
„Applicability of Output Modifiers“ (Section 9.3)
„Metadata Objects“ (Section 10.8)

How?

Add to table

HTTP DELETE throws 404

What?

Requesting a DELETE on a not existent resource throws 404.

How?

What should be achieved with such a call is that the resource is gone after the call is completed. If it was not there before, the desired target state is already reached prior to the method call. In the sense of fault tolerance and better applicability of the API, it could also return 200. This saves the client side from having to handle the 404 in these cases.

Add Interface Profiles

(placeholder for further discussion)

Change link in "About" section of this github project

What?

About
Repository of the Asset Administration Shell - API
www.plattform-i40.de

shall be changed to

About
Repository of the Asset Administration Shell - API
www.industrialdigitaltwin.org

No mandatory Field to display Identifiables in a UI

What?

Neither IdShort nor Display name for AAS and Submodels are mandatory. One at least should be mandatory to have something to display in UIs.

How?

Add constraint that idShort is required for Identifiables and shall be a fall-back if no displayName is provided.

This issue relates to finding Go#5 and needs to be discussed in the Part 1 WG.

Output Modifiers should NOT be applied to POST APIs

What?

API: All the POST APIs
Description of API: Create requested AAS element
Finding:
Current : Output modifiers are present in the API.

How?

Output Modifiers should NOT be applied to POST APIs.

rename environment interfaces to repostiory interface as in previous versions

What?

rename interface to previous names:
Asset Administration Shell Environment &
Asset Administration Shell Environment Serialization API
==>
Asset Administration Shell Repository &
Asset Administration Shell Repository Serialization API

A repository is a database and these interfaces are designed to be used by architectural components like databases offering the interface. This has nothing to do with the class "environment" of the metamodel. Environment of the metamodel is just for structuring, it is not identifiable or referable.

Was discussed in Part 1 review, a note was added:
"Note: Environment is not an identifiable or referable element. It is introduced to enable file transfer as well as serialization."

Option to Identify and track Error Messages

"Identifiable" error messages, message causes/descriptions need a stronger typization than 'string'

Multilanguage descriptions in the root cause descriptions not available.

Issue relates to finding basis#01.

Base64 with padding or not

What?

BASE64 URL encoding - specification does not make clear if "padding" must be included or not.

See for example on the bottom of https://www.base64url.com : "Some variants allow or require omitting the padding '=' signs to avoid them being confused with field separators, or require that any such padding be percent-encoded. Some libraries will encode '=' to '.'.

How?

Explicitely include in the design decisions if "padding" must be included or not within BASE64 URL encoding

This issue relates to finding IDTA_Repo_1.

Don't Allow Output Modifiers for POST APIs

What?

...

How?

...

This issue relates to finding XX#??.

Multiple idShort Parameters in GetAllAssetAdministrationShellsByIdShort possible

Finding: SB#1

What?

The attributes 'style: form' and 'explode: true' lead to the option to add the idShort parameter several times in the GET request, e.g. http://localhost/shells?idShort=id-short-1&idShort=id-short-2
(see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject)

What is the semantics between the two idShort values?

Proposed Change:

Mark the parameter as an array in SwaggerHub and declare an OR semantics between the values of the one parameter group but an AND semantics between different parameter groups

Update Sequence Diagram Fig. 6

What?

Fig. 6 appears like a typical UML sequence diagram but uses several patterns which are not really common, e.g.:

• confusing to use GET PUT DELETE
• operations ()
• Shell Repository is not included
• source file missing
• Interface Shell Repository is not used
• AAS Interface does not only return Endpoint of AAS but also of its submodels
• how to find the Submodel registry endpoint (central registry?)
• additional diagrams missing
  • automatically configured infrastructure
  • instantiate and register
  • Publish and discovery
  • check access rights
• wrong comment

How?

Create a new version of the diagram and a few additional ones.

This issue relates to the findings Bo-#22 to Bo-#37.

Extend Error Messages

What?

Error messages do not have an id, therefore cannot be tracked. Furthermore, there is no option to supply descriptions in different languages.

How?

Add a field Message/correlationId.
Add Multilanguage descriptions in the root cause descriptions.

This issue relates to finding Basys#1.

Submodel API: Output Modifiers in POST and PUT operations

What?

According to the Part2 document, output modifiers are actually not intended for describing the input data of a POST/PUT request. However, the the Swagger definition suggests this ("content: Determines the request (!) or response kind of the resource") for PostSubmodelElementByPath and PutSubmodelElementByPath

Nevertheless, as identified by Juilee (slide 9), default modifiers (Deep, Normal, WithoutBlobValue) which are in this case rather content descriptors can be seen as a "ReplaceAll". Updating an existing submodel element hierarchy with "non-default" content, e.g. value or metadata trees may lead to inconsistencies if the update contains partial elements that do not exist yet or misses existing elements.

How?

In order to allow an easier implemention, I would suggest to:

• remove the output modifier parameters from PostSubmodelElementByPath. This doesn't make sense here at all.
• remove them also from PutSubmodelElementByPath. The levels and extents are not really applicable here.
• Instead define a "content description" enumeration [FULL, META, VALUE] as input parameter with the following semantics
  • FULL: full content is provided in the request body for a ReplaceAll style operation. This applies to both atomic submodel elements as well as element collections targeted by the IdShort path.
  • META: update the metadata of the submodel element targeted by the IdShort path. Don't touch the children if this is an element collection. (a Core level with direct children is actually to much)
  • VALUE: update the value of an atomic Data Element (excl. Range, contains just metadata?). This is especially feasible for low-power/bandwidth devices.

This should render the introduction of a PATCH method obsolete (for now).

Relates to #32

(still) ToDo: Update OpenAPI and Spec.

Interpretation of Output Modifiers Content = Metadata

What?

Section: 9.2, 10.5 & 10.7
Output Modifiers: Content = Metadata
Finding: Inconsistent Definitions in above sections

How?

Modification in Table from Section 10.5 & 10.7
Combination Content = Metadata & Extent = WithBLOBValue NOT allowed, because the definitions of metadata and WithBlobValue are inconsitent with each other as described below:
Metadata: Value should be excluded.
WithBLOBValue: a Value should be returned with Base64Encoding

GetAllSubmodelsBySemanticId oversimplifies the Reference Value

The QueryParameter https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V1.0RC03#/components/parameters/SemanticId is a base64 encoded string.

The value of semanticId however is Reference, which shall be represented as a object or a more detailed description provided that the complete Reference object is base64-encoded and not only a value of one Key.value. As there can be more keys in a Reference, on Key.value is - in general - not enough.

Inconsistent Output Modifiers with Submodels

What?

API: GetSubmodel (Within AAS) & GetSubmodelById in Environment-API

Description of API: Returns a specific Submodel
Section: 6.3.3
Finding:

• GetSubmodel (Within AAS) API has output modifiers

• GetSubmodelById API does NOT have output modifiers

REST Path of the API: /submodels/{submodelIdentifier} (GET)

How?

Adding OutputModifiers to the API GetSubmodelById

Terminology: 'API Operation' vs. SME 'Operation'

What?

The term 'operation' for API operations (e.g. GetAssetAdministrationShell) is confusing, given that it also signifies a metamodel concept in part 1.

How?

Find a synonym.

This issue relates to admin-shell-io/aas-specs#19.

Single Value for globalAssetId

What?

The globalAssetId is an array of String values.
This is misleading because only one GlobalAssetId can exists for a AAS.

How?

The globalAssetId should only accept one single value.

This issue relates to the finding Fethualla#1 and needs to be discussed in the Part 1 WG.

Reference Output Modifier is missing for GetAasById

What?

... but is written so in the document.

How?

Add the output modifier.

This issue relates to finding XX#??.

Query Parameter for GetAllAssetAdministrationShellIdsByAssetLink faces implicit length limit

What?

The GET /lookup/shells?assetIds is limited by URL length limits.
A long value of assetIds can exceed the length.

How?

Introduce a POST /lookup/shells where the assetIds can be provided in the payload.

This issue relates to finding Fe#6.

Unsafe API Operations with Content != normal

Creation of incomplete Submodels is currently possible via, for instance, PostSubmodelElementByPath with content=value. However, the server cannot guess the missing attributes, making this a dangerous API Operation.

Might relate to the finding Rössl#4.

ToDo: Add to spec that POSTing incomplete submodels is not allowed.

Different formats of ValueOnly-Serialization for AnnotedRelationshipElement/Annotations and Entity/Statements

What?

Section: 9.4.2
Finding: Different formats of ValueOnly-Serialization for AnnotedRelationshipElement/Annotations and Entity/Statements

How?

...

This issue relates to finding XX#??.

Output Modifiers: Level = Core & Content = Value

What?

Section: 9.2
Output Modifiers: Level = Core & Content = Value
Finding:
Current Definitions: Core: Requested element + Direct Children
Value: Raw Value of element
Ultimately, Core + Value = Deep + Value

How?

If direct child is hierarchical element, ValueOnly serialization of this element = „IdShort“:{ }/[ ]

Enable more Query Parameters for the AAS Registry

Currently, GetAssetAdministrationShellDescriptorById only allows filtering for the id. More attributes, e.g. assetKind, can dramatically improve the search performance.

Open question: Shall all metamodel attributes be allowed? If so, is there still a difference between an AssetAdministrationShell and an AssetAdministrationShellDescriptor?

relates to finding BO#67.

duplicate of #16

Documentation: Metadata not specific to HTTP: move to chapter 9

What?

In chapter 9 of the specification the operation parameters are explained on conceptual level. However, the table explaining metadata objects, 10.5, is part of chapter "HTTP/REST API".
The chapter 9 starts with explaining these are parameter for API operation, not for Interface-Operations (on conceptual level). I assume it is conceptual level.

How?

Either move 10.5 to 9 or after as separate chapter.
Or more parameter chapter to HTTP/REST Chapter.

Output Modifiers missing for GetSubmodelById

What?

...

How?

...

This issue relates to finding XX#??.

Interface for Creating whole Environments

What?

There is no API to create the whole AAS environment. If there is an AAS files with 10 submodels, there will be 11 calls which will have to happen in a specific order. AAS call first and others afterwards. This is one of the common use case of catena x. /aasx url is not sufficient since creating an aasx file is an unnecessary overhead for just json/xml files.

How?

Create an additional API like /v1/env/.

This issue relates to finding Go#7.

Plural Attributes in Descriptors

AssetAdministrationShellDescriptor and SubmodelDescriptor have the attributes descriptions and displayNames, which appear now as non-plural form in the metamodel. To keep it consistent, also singular names should be used in the Descriptors.

Use standardized Key Words in the Document

What?

Common key words like "MUST", "MUST NOT" etc. are not used in the Part 2 document.

How?

Rewirte the document by using the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" as described in BCP 14 RFC2119 RFC8174.

This issue relates to the finding Bo-#1.

Pagination for Response Content

Paging or pagination is a common pattern to cope with huge result lists. Especially GetAllAssetAdministrationShells or GetAllSubmodels can easily return thousands or millions of objects.

Patterns could be:

1. (Max)pagesize plus page number
2. Limit and offset
3. Server-side paging using a next link parameter (e.g. https://learn.microsoft.com/en-us/odata/client/pagination#server-driven-paging)
4. client-side paging using $skip and $top (might be the same pattern as 2.) (e.g. https://learn.microsoft.com/en-us/odata/client/pagination#client-driven-paging)

Prerequisite: The AAS Identifiables (or all AAS elements?) need to have a natural or selectable order, e.g., alphabetical, chronological, by relevance etc.

Challenge: Even one Submodel could become arbitrarily large, which might require partitions also within one Identifiable.

Bulk/Batch Requests

Add a request pattern to allow sending of more than one API Operation with one request. A reference might be the OData Batch Requests: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31359017

This feature also opens the door for general asynchronous API Operations. (Note: API Operations as meant in this issue is not referring to an invocation of the SubmodelElement Operation.)

HTTP PUT throws 404

What?

Performing an update of a non existing resource via PUT throws 404.

How?

Instead (for the same reasons as in #39), it could be created (returning 201) if the identifier in the path matches the one in the body. Otherwise return 400. In that case, PUT is kind of a CreateOrUpdate method.

In the Submodel API, PutFileByPath also follows a CreateOrUpdate style. If the File element value is empty, the "attachment" is created. However, returning 204 instead of 201 seams reasonable.

For PutSubmodelElementByPath, the proposed behavior should probably only be possible if the path segments match up to the last segments taking into account #32 and #33.

Add assetKind and assetType to AAS Descriptor

What?

https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection/V1.0RC03#/Asset%20Administration%20Shell%20Registry%20API/GetAssetAdministrationShellDescriptorById

assetKind and assetType (new with V3.0) is part of the AssetInformation of an AAS. It should be part of the AAS descriptor as well because often lookup is done for specificAssetId manfuacturer = ABC and assetKind = Type

and some bugfixes:

• it is not descriptions but description (0..1, multi-language)
• it is not displaynames but displayname (0..1, mulit-language)

How?

add assetKind and assetType to schema for AssetAdministrationShellDescriptor + make bugfixes

Modifier Constraints - idShort

What?

Documentation, chapter 10.7 Modifier Constraints
• If Level=Core and Content=Value, then only the requested object and the direct children without their value (empty value) will be returned in value serialization. If a direct child is a SubmodelElementCollection, “idShort : {}” will be returned. If a direct child is a SubmodelElementList, “idShort : []” will be returned.

When Content=Value the idShort is never returned as an attribute name. it would probably be : {}. SAme for direct childs : []

I personally would not allow to combine Level=Core and Content=Value

How?

Do not allow Level=Core and Content=Value
or
correct rule (see above)

Result Objects are not Type-Safe

What?

We're trying to improve the compatibility of assets between different organisations and technologies. Thus we should try to create APIs, that can be realized in at least the majority technologies. The strategy of modifying result structures via query parameters results in bad implementations. The majority of implementation frameworks expects a polymorph result. Typesafety is a general requirement from a technology independent view. An endpoint, that returns in one case a Submodel, in the next a Reference or a simple, idShort-Name based map, has as return type "Object"/"Any" - a clear anti-pattern in most environments.

An URL Path like /shells/<id>/submodels/<id>/submodel/metadata or /shells/<id>/submodels/<id>/submodel/reference result in very much clearer interfaces, that can be implemented straight in most technologies - with typesafety. An interfaces specification, that can't be expressed in RDF / swagger, most probably doesn't follow best practices guides.

How?

Switch to explicit endpoints, that accept/produce structures, that can be documents in rdf / swagger.

This issue has been raised as IDTA_Repo_4.

Missing Field Lengths

What?

The API Spec does not define field lengths - min and max values for fields. For instance:
How long can a specificAssetId key be?
How long can a description be?
etc.

How?

Define appropriate field lengths for each field.

This issue relates to finding Fe#2.

SubmodelDescriptor/semanticId is an Array

What?

The semanticId for the SubmodelDescriptor is an array:

"semanticId": {
    "value": [
      "urn:bamm:com.catenax.vehicle:0.1.1"
    ]
  }

This is confusing because only one SemanticId makes sense here.

How?

Change this to: 

"semanticId": {
    "value": {
      "urn:bamm:com.catenax.vehicle:0.1.1"
    }
  }

This issue relates to finding Fe#8 and needs to be discussed in the Part 1 WG.

PUT: ValueOnly serialization of File and BLOB are same

What?

API: PUT
Description of API: Updates an existing submodel element
Output Modifier: Content = Value
Section: 9.4.2
Finding:
ValueOnly serialization of File and BLOB are same.
Difficulty in distinguishing „modelType“ in case of PUT

Disable structural changes through PUT

What?

API: PUT
Description: Update the resource
Section: 9.2
Output Modifiers: Default (Deep, Normal, WithoutBlobValue)
Finding:
Structural changes are allowed
Completely replace the resource

How?

PATCH ?

Support Technical ID besides logical ID for AAS and Submodels (Identifiables) in Registry and Repository

What?

In practice identifier are typically created by a system and not created manually. So when registering a new AAS we should distinguish:

logicalID (AssetAdministrationShell/id) from customer/caller of API operation (can be http etc.), theoretically the ID could be changed by the caller at a later stage
technicalID system created, cannot be changed by user. Supports very performant queries whereas logicalIDs (and any strings allowed) will slow down search when it comes to millions of AAS to be managed

TechnicalID (AssetAdministationShell/technicalID) is mandatory, logical ID (AssetAdministraionShell/id) is optional but as a default it is identical to technical ID.

• if logicalID not given then logicalID = technialID
• if both are given then they can differ, only logicalID can be overwritten

How?

extends/change metamodel part 1 (introduce techncialID and make AAS/id optional)
and
change AASDescriptor and SubmodelDescirptor. In Descirptor both are optional: - if technicalID not given (although mandaotry in metamodel) then technicalID = logicalID

Add more Parameters to the Registry Interface

What?

Only the AAS Id can be used to search for desired shells. That's a very inefficient pattern.

How?

Add more parameters, e.g. assetKind.

This issue relates to finding Bo#67.

duplicate to #7

Split Submodel API

What?

https://app.swaggerhub.com/apis/Plattform_i40/Submodel-API/V1.0RC03

Access Control Rules for single submodel elements were introduced because of the view concept (example: safety view). However, since there are no views any longer this capability is optional.
With EDC Connector it is the complete submodel that is accessed and get an access policy assigned.

Split Submodel API into two APIs:

==>
Submodel API

and
Whitebox Submodel API

How?

see What (in specification document and in swagger)

This issue relates to finding XX#??.
#5 Profiles

If Profiles allow to only have a subset of the operations then this is also possible and the interface itself does not need to be split.

APIs NOT getting generated by Swagger Code Generation (Server Stub aspnetcore)

What?

API:

• AssetAdministrationShellEnvironmentApi
  • PutFileByPath
• AasxFileServerInterfaceApi
  • PostAASXPackage
  • PutAASXPackageById
    Description of API: Create or update file or Aasx-Package
    Finding:
    Issue: APIs NOT getting generated by Swagger
    Workaround: Manual Addition in the code

Missing "format: byte" in Base64URL-encoded parameters

What?

The format is missing in

• GET /shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}
• PUT /shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}
• DELETE /shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier}

It could probably also be specified in

• GET /serialization

It seems, there is a typo (bytev) in

• POST /lookup/shells/{aasIdentifier}

How?

...

This issue relates to finding XX#??.

Introduce Event Interfaces

The metamodel knows EventElements and EventPayloads. The Interface Operations also imply - to some degree - an event character (e.g. PostSubmodelElementByPath --> send the event CreateSubmodelElement with a path information). The API Operations however are still restricted to RESTful/HTTP operations.

We need to introduce a generic event handling (Event Interface Operations?) together with reference Event API Operations for, e.g., MQTT, OPC UA, gRPC or other commonly used protocols.

Output Modifiers NOT present at GetAllAssetAdministrationShells & GetAssetAdministrationShellById

What?

API: GetAllAssetAdministrationShells & GetAssetAdministrationShellById
Description of API: Returns a specific Asset Administration Shell
Section: 6.2.2 & 6.2.3
Finding:
Current: Output Modifiers NOT present
Suggestion: Output Modifiers (Content) should be present

How?

OpenApiSpec (OAS) Links

What?

Add OpenApiSpec (OAS) Links to the Spec to specify the relationship of routes within OAS, e.g. which responses of which routes can be used for a request to another route. These definitions allow automated stateful testing with certain testing libraries.

How?

Add links to the spec.

This issue relates to finding ACPLT-5.