Async AASX File Server Profile (#531)

sebbader-sap · web-flow · commit 257ef8dc9d25 · 2026-03-29T16:26:33.000+02:00
* add proposal for an async aasx profile

* correct result of the get .../results/... endpoint

* add missing appearances of the async aasx file server operations
diff --git a/AasxFileServerServiceSpecification/V3.2_SSP-002.yaml b/AasxFileServerServiceSpecification/V3.2_SSP-002.yaml
@@ -0,0 +1,153 @@
+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/HandleId'
+    get:
+      tags:
+        - AASX Async File Server Result API
+      summary: Returns the result of an asynchronously 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/BaseOperationResult'
+        '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'
diff --git a/Entire-API-Collection/V3.2.yaml b/Entire-API-Collection/V3.2.yaml
@@ -7536,6 +7536,110 @@ paths:
           $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:
+    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/HandleId'
+    get:
+      tags:
+        - AASX Async File Server Result API
+      summary: Returns the result of an asynchronously 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/BaseOperationResult'
+        '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'
+
 
 
   /serialization:
diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc
@@ -14,6 +14,7 @@ Note: Changes in Metamodel (IDTA-01001) will not be listed here, although they h
 
 Major Changes:
 
+* Add the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
 * Changing the serialization format for AASX packages from "application/asset-administration-shell-package+xml" to "application/aas+zip" in the OpenAPI files for the Asset Administration Shell Repository Service Specification and the Submodel Repository Service Specification. This change is necessary to align with the actual content type used by implementations and to avoid confusion, as the previous content type was not registered and could be misinterpreted as an XML-based format. (https://github.com/admin-shell-io/aas-specs-api/issues/538[#538])
 
 
@@ -25,14 +26,16 @@ Minor Changes:
 * Editorial: Remove links to SwaggerHub from the HTTP API section, as the links are maintained in the service specifications and profiles sections. (https://github.com/admin-shell-io/aas-specs-api/issues/475[#475])
 * Editorial fixes in Table 2 of the Query Language specification (https://github.com/admin-shell-io/aas-specs-api/issues/507[#507])
 
-
 === Operation Changes w.r.t. V3.1.1 to V3.2
 
 [%autowidth,width="100%",cols="40%,15%,45%",options="header",]
 |===
 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])
 |===
 
 
diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc
@@ -582,6 +582,9 @@ Pagination
 |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 |GET |/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
@@ -687,6 +690,28 @@ Note: the invocation of the SubmodelElement "Operation" may also be conducted in
 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.
diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc
@@ -320,6 +320,7 @@ See: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelServiceSpecification/
 |===
 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 @@ AASX for packages
 
 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
 
diff --git a/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc b/documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc
