admin-shell-io · sebbader-sap · Mar 29, 2026 · Feb 7, 2026 · Feb 13, 2026 · Feb 27, 2026
@@ -0,0 +1,154 @@
+openapi: 3.0.3
+info:
+  title: DotAAS Part 2 | HTTP/REST | AASX File Server Service Specification
+  description: >-
+    The async profile of the File Server Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](http://industrialdigitaltwin.org/en/content-hub).
+
+    Publisher: Industrial Digital Twin Association (IDTA) 2026
+  contact:
+    name: Industrial Digital Twin Association (IDTA)
+    email: info@idtwin.org
+  license:
+    name: CC BY 4.0
+    url: https://creativecommons.org/licenses/by/4.0/
+  version: V3.2.0_SSP-002
+  x-profile-identifier: https://admin-shell.io/aas/API/3/2/AasxFileServerServiceSpecification/SSP-002
+  termsOfService: https://github.com/admin-shell-io/aas-specs
+servers:
+- url: 'https://admin-shell.io/api/v3'
+- url: 'https://example.com'
+paths:
+  /packages-async:
+
+    post:
+      tags:
+        - AASX Async File Server API
+      summary: Initiates an asynchronous upload of an AASX package at the server.
+      operationId: PostAsyncAASXPackage
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/PostAsyncAASXPackage/3/2
+      requestBody:
+        description: AASX package
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                aasIds:
+                  type: array
+                  items:
+                    type: string
+                file:
+                  type: string
+                  format: binary
+                fileName:
+                  type: string
+            encoding:
+              file:
+                contentType: application/asset-administration-shell-package
+        required: true
+      responses:
+        '202':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/accepted'
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/bad-request'
+        '401':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/unauthorized'
+        '403':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/forbidden'
+        '409':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/conflict'
+        '500':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/internal-server-error'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/default'
+
+  /packages-async/status/{handleId}:
+    parameters:
+      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/parameters/HandleId'
+    get:
+      tags:
+        - AASX Async File Server Status API
+      summary: Returns the status of an asynchronously invoked AASX operation.
+      operationId: GetAasxAsyncStatus
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/GetAasxAsyncStatus/3/2
+      responses:
+        '200':
+          description: Operation result object containing information that the 'executionState' is still 'Running'
+          content:
+            application/json:
+              schema:
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/schemas/BaseOperationResult'
+        '302':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/found'
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/bad-request'
+        '401':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/unauthorized'
+        '403':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/forbidden'
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/not-found'
+        '500':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/internal-server-error'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/default'
+  /packages-async/results/{handleId}:
+    parameters:
+      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/parameters/IdShortPath'
+      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/parameters/HandleId'
+    get:
+      tags:
+        - AASX Async File Server Result API
+      summary: Returns the Operation result of an asynchronous invoked AASX operation.
+      operationId: GetAasxAsyncResult
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/GetAasxAsyncResult/3/2
+      responses:
+        '200':
+          description: Operation result object
+          content:
+            application/json:
+              schema:
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/schemas/OperationResult'
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/bad-request'
+        '401':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/unauthorized'
+        '403':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/forbidden'
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/not-found'
+        '500':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/internal-server-error'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/default'
+
+
+  /description:
+    get:
+      tags:
+        - Description API
+      summary: Returns the self-describing information of a network resource (ServiceDescription)
+      operationId: GetDescription
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/Descriptor/GetDescription/3/2
+      responses:
+        '200':
+          description: Requested Description
+          content:
+            application/json:
+              example: "https://admin-shell.io/aas/API/3/2/AasxFileServerServiceSpecification/SSP-002"
+              schema:
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/schemas/ServiceDescription'
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/bad-request'
+        '403':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/forbidden'
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/not-found'
+        '500':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/internal-server-error'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.2.0#/components/responses/default'
@@ -14,12 +14,13 @@
 
 Major Changes:
 
-* ...
+* Add the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
 
 
 Minor Changes:
 
 * Added the `ServerNotImplemented` status code to the xref:specification/interfaces-payload.adoc#table-status-codes[Status Codes]. Note that the HTTP API mentioned this status code already, therefore, no change in OpenAPI or other related files. (https://github.com/admin-shell-io/aas-specs-api/issues/499[#499])
+* Removed the `GetAllAssetAdministrationShellDescriptorsByAssetType` operation from the OpenAPI files for the Asset Administration Shell Registry Service Specification, as it was not intended to be included in the first place and is not implemented by any known implementation. (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
 
 
 
@@ -30,6 +31,9 @@
 h|Operation  h|Kind of Change h|Comment
  | GenerateSerializationByIds|change a| Added a note to clarify the intended behavior for transitively referenced concept descriptions. (https://github.com/admin-shell-io/aas-specs-api/issues/510[#510])
  | PutAssetAdministrationShellById|change a| Added the missing `id` input parameter and a note explaining the behavior in case the AAS identifier does not match the value of `id`. (https://github.com/admin-shell-io/aas-specs-api/issues/506[#506])
+ | PostAsyncAASXPackage|new a| New API Operation for the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
+ | GetAasxAsyncStatus|new a| New API Operation for the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
+ | GetAasxAsyncResult|new a| New API Operation for the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
 |===
 
 

@@ -598,9 +598,12 @@
 |GetAASXByPackageId |GET |/packages/\{packageId} |base64url-encoded identifier
 |PutAASXByPackageId |PUT |/packages/\{packageId} |base64url-encoded identifier
 |DeleteAASXByPackageId |DELETE |/packages/\{packageId} |base64url-encoded identifier
+|PostAsyncAASXPackage |POST |/packages-async |
+|GetAasxAsyncStatus |DELETE |/packages-async/\{handleId} |
+|GetAasxAsyncResult |GET |/packages-async/result/\{handleId} |
 
 4+h|Serialization Interface
 |GenerateSerializationByIds |GET |/serialization |base64url-encoded identifier; AcceptHeader: application/aasx+xml or application/json oder application/xml

 4+h|AAS Basic Discovery Interface
 |GetAllAssetAdministrationShellIdsByAssetLink |GET |/lookup/shells a|
@@ -703,6 +706,28 @@
 In this case, the "/$value" path segment is added to the previously mentioned endpoints.
 ====
 
+
+[#async-invocation-of-aasx-upload]
+== Asynchronous Invocation of an AASX File Upload
+The upload of an AASX file is only defined as an asynchronous operation in the current version of the specification.
+The expected behavior is therefore explained in detail.
+.Sequence for asynchronous AASX file upload
+[[aasx-upload-invocation]]
+[plantuml, aasx-upload-invocation, svg]
+....include::partial$diagrams/aasx-upload-invocation.puml[]
+....
+The client sends a POST request to the "/packages-async" endpoint with the AASX file in the request body.
+The server immediately responds with an Accepted (status code: 202) message containing the link to an endpoint where the client can fetch status information about his request (see <<aasx-upload-invocation>>).
+This status endpoint is located at "/packages-async/\{handleId}".
+In case the request is incorrect and the server already recognizes it, the server responds directly with the according status code, e.g. 400. If the server can only recognize the error during later processing and not at the time it receives the request, it responds with an Accepted (202) message at first. Hence, a received Accepted message does not guarantee the client that its request is valid in every case.
+If the server has not finished processing the request, the status endpoint responds with a message with the attribute "executionState" set to "Running".
+As soon as the processing is finished, the status endpoints deliver a Found (HTTP status code 302) response with the location of the result in the Location response header.
+The result is provided at the "/packages-async/result/\{handleId}" endpoint.
+In case incorrect inputs have been provided by the client but the server was only able to recognize this during processing, or if the server perceived any other error during processing, the server must still provide the result object with status code 200 and set the attribute "executionState" to "Failed".
+
+
+
+
 == Bulk Operations
 
 This chapter provides a description of the Bulk APIs.

@@ -320,6 +320,7 @@
 |===
 h|Service Specification / Profiles h|Description
 |<<aasx-file-server-service-specification-SSP-001, AasxFileServerServiceSpecification/SSP-001>>The full feature set of the AASX File Server Service Specification
+|<<aasx-file-server-service-specification-SSP-002, AasxFileServerServiceSpecification/SSP-002>>The async feature set of the AASX File Server Service Specification
 |===
 
 [#aasx-file-server-service-specification-SSP-001]
@@ -352,6 +353,34 @@
 
 See: https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.2.0_SSP-001
 
+[#aasx-file-server-service-specification-SSP-002]
+=== AASX File Server Service Specification – Async Profile
+
+[%autowidth,width="100%",cols="36%,64%",options="header",]
+|===
+h|Name:  |AASX File Server Async Profile
+h|Profile Identifier |`\https://admin-shell.io/aas/API/3/2/AasxFileServerServiceSpecification/SSP-002`
+h|Feature  h|Appearance
+|APIs and API Operations a|
+_File Server API:_ +
+xref:specification/interfaces.adoc#InvokeOperationAsync[InvokeOperationAsync] +
+xref:specification/interfaces.adoc#GetAasxAsyncStatus[GetAasxAsyncStatus] +
+xref:specification/interfaces.adoc#GetAasxAsyncResult[GetAasxAsyncResult]
+
+_Description API:_ +
+xref:specification/interfaces.adoc#GetSelfDescription[GetDescription]
+
+|xref:specification/interfaces-operation-parameters.adoc#SerializationModifier[SerializationModifier] |not applicable
+|SerializationFormat a|
+JSON for descriptions and error messages
+
+AASX for packages
+
+|xref:http-rest-api/http-rest-api.adoc#pagination[Pagination] |not supported
+|===
+
+See: https://app.swaggerhub.com/apis/Plattform_i40/AasxFileServerServiceSpecification/V3.2.0_SSP-002
+
 [#asset-administration-shell-registry-service-specification]
 == Asset Administration Shell Registry Service Specification
 

@@ -694,6 +694,9 @@
 e|xref:PostAASXPackage[PostAASXPackage] |Creates an AASX package at the server
 e|xref:PutAASXByPackageId[PutAASXByPackageId] |Replaces or creates the AASX package at the server
 e|xref:DeleteAASXByPackageId[DeleteAASXByPackageId] |Deletes a specific AASX package
+e|xref:PostAsyncAASXPackage[PostAsyncAASXPackage] |Initiates an asynchronous upload of an AASX package at the server.
+e|xref:GetAasxAsyncStatus[GetAasxAsyncStatus] |Returns the status of an asynchronously invoked AASX Operation.
+e|xref:GetOperationAsyncResult[GetOperationAsyncResult] |Returns the Operation result of an asynchronously invoked AASX operation.
 |===
 
 ==== Operation GetAllAASXPackageIds
@@ -807,6 +810,64 @@
 |statusCode |Status code |yes |xref:specification/interfaces-payload.adoc#StatusCode[StatusCode] |1
 |===
 
+==== Operation PostAsyncAASXPackage
+
+[.table-with-appendix-table]
+[width=100%,cols="25%,35%,10%,20%,10%"]
+|===
+h|Operation Name 4+e|[[PostAsyncAASXPackage]]PostAsyncAASXPackage
+h|Explanation 4+a|Initiates an asynchronous upload of an AASX package at the server
+h|semanticId 4+|`\https://admin-shell.io/aas/API/PostAsyncAASXPackage/3/2`
+
+h|Name h|Description h|Mand. h|Type h|Card.
+5+h|Input Parameter
+|file |New AASX package |yes |link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01005/v3.1/index.html[AASX package] |1
+|filename |Filename of the AASX package |yes |string |1
+5+h|Output Parameter
+|statusCode |Status code |yes |xref:specification/interfaces-payload.adoc#StatusCode[StatusCode] |1
+|payload |The returned handle of an operation’s asynchronous invocation used to request the current state of the operation’s execution |yes | xref:specification/interfaces-payload.adoc#OperationHandle[OperationHandle] |1
+|===
+
+
+==== Operation GetAasxAsyncStatus
+
+[.table-with-appendix-table]
+[width=100%,cols="25%,35%,10%,20%,10%"]
+|===
+h|Operation Name 4+e|[[GetAasxAsyncStatus]]GetAasxAsyncStatus
+h|Explanation 4+a|Returns the status of an asynchronously invoked AASX Operation
+h|semanticId 4+|`\https://admin-shell.io/aas/API/GetAasxAsyncStatus/3/2`
+h|Name h|Description h|Mand. h|Type h|Card.
+5+h|Input Parameter
+|todo | todo |yes |string |1
+5+h|Output Parameter
+|statusCode |Status code |yes |xref:specification/interfaces-payload.adoc#StatusCode[StatusCode] |1
+|payload |Execution state of the operation |yes | xref:specification/interfaces-payload.adoc#BaseOperationResult[BaseOperationResult] |1
+|===
+
+
+
+==== Operation GetAasxAsyncResult
+
+[.table-with-appendix-table]
+[width=100%,cols="25%,35%,10%,20%,10%"]
+|===
+h|Operation Name 4+e|[[GetAasxAsyncResult]]GetAasxAsyncResult
+h|Explanation 4+a|Returns the Operation result of an asynchronously invoked AASX operation
+h|semanticId 4+|`\https://admin-shell.io/aas/API/GetAasxAsyncResult/3/2`
+
+h|Name h|Description h|Mand. h|Type h|Card.
+5+h|Input Parameter
+|operationHandle |The returned handle of an operation’s asynchronous invocation used to request the current state of the operation’s execution |yes |xref:specification/interfaces-payload.adoc#OperationHandle[OperationHandle] |1
+5+h|Output Parameter
+|statusCode |Status code |yes |xref:specification/interfaces-payload.adoc#StatusCode[StatusCode] |1
+|payload |Operation Result |yes |xref:specification/interfaces-payload.adoc#OperationResult[OperationResult] |1
+|===
+
+
+
+
+
 [#registration-interfaces]
 == Registration Interfaces