Adjust OpenAPI Files for Discovery Service Profiles (#229)

sebbader-sap · BirgitBoss · web-flow · commit 4d221ed763a3 · 2025-01-05T13:07:26.000+01:00
* add Discovery Service Specification V3.1_SSP-001 as own YAML file

* adjust name of Discovery Service Specification SSP-002

* correct links from v3.0.1 to v3.1.0

* Update DiscoveryServiceSpecification/V3.1_SSP-001.yaml

---------

Co-authored-by: Birgit Boss &lt;59824205+BirgitBoss@users.noreply.github.com&gt;
diff --git a/DiscoveryServiceSpecification/V3.0_SSP-001.yaml b/DiscoveryServiceSpecification/V3.0_SSP-001.yaml
@@ -11,83 +11,62 @@ info:
   license: 
     name: CC BY 4.0
     url: https://creativecommons.org/licenses/by/4.0/
-  version: V3.1.0_SSP-001
-  x-profile-identifier: https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001
+  version: V3.0.3_SSP-001
+  x-profile-identifier: https://admin-shell.io/aas/API/3/0/DiscoveryServiceSpecification/SSP-001
 servers:
-- url: 'https://admin-shell.io/api/v3.1'
-- url: 'https://example.com/'
-
+- url: '{protocol}://{host_name}:{port}/api/{version_prefix}'
+  variables:
+    protocol:
+      description: 'Allows access through http and https (recommended)'
+      enum:
+        - 'http'   
+        - 'https'
+      default: 'https'
+    host_name:
+      default: admin-shell.io
+      description: 'Hostname of server hosting the api'
+    port:
+      enum:
+        - '80'
+        - '443'
+      default: '443'
+      description: '80 is default for http, 443 for https'
+    version_prefix:
+      enum:
+        - 'v3.0'
+      default: v3.0
 paths:
   /lookup/shells:
     get:
-      deprecated: true
       tags:
         - Asset Administration Shell Basic Discovery API
       summary: Returns a list of Asset Administration Shell ids linked to specific Asset identifiers 
       operationId: GetAllAssetAdministrationShellIdsByAssetLink
       x-semanticIds:
         - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellIdsByAssetLink/3/0
       parameters:
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetIds'
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/parameters/AssetIds'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/parameters/Limit'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/parameters/Cursor'
       responses:
         '200':
           description: Requested Asset Administration Shell ids
           content:
             application/json:
               schema:
                 allOf:
-                - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
+                - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/schemas/PagedResult'
                 - type: object
                   properties:
                     result:
                       type: array
                       items:
                         type: string
         default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
-  /lookup/shellsByAssetLink:
-    post:
-      tags:
-        - Asset Administration Shell Basic Discovery API
-      summary: Returns a list of Asset Administration Shell ids linked to specific Asset identifiers 
-      operationId: SearchAllAssetAdministrationShellIdsByAssetLink
-      x-semanticIds:
-        - https://admin-shell.io/aas/API/SearchAllAssetAdministrationShellIdsByAssetLink/3/1
-      parameters:
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
-        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
-      requestBody:
-        description: A list of asset identifiers in the form of an AssetLink each. One AssetLink may either represent the name/value pair of a SpecificAssetId or the globalAssetId of the asset represented by the Asset Administration Shell.
-        content:
-          application/json:
-            schema:
-              type: array
-              items:
-                '$ref': 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/AssetLink'
-      responses:
-        '200':
-          description: Requested Asset Administration Shell ids
-          content:
-            application/json:
-              schema:
-                allOf:
-                - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
-                - type: object
-                  properties:
-                    result:
-                      type: array
-                      items:
-                        type: string
-        '400':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
-        default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
-
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/default'
   /lookup/shells/{aasIdentifier}:
     parameters:
-      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetAdministrationShellIdentifier'
+      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/parameters/AssetAdministrationShellIdentifier'
     get:
       tags:
         - Asset Administration Shell Basic Discovery API
@@ -103,11 +82,11 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.0.3#/components/schemas/SpecificAssetId'
         '404':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/not-found'
         default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/default'
     post:
       tags:
         - Asset Administration Shell Basic Discovery API
@@ -122,7 +101,7 @@ paths:
             schema:
               type: array
               items:
-                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.0.3#/components/schemas/SpecificAssetId'
         required: true
       responses:
         '201':
@@ -132,15 +111,15 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.0.3#/components/schemas/SpecificAssetId'
         '400':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/bad-request'
         '404':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/not-found'
         '409':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/conflict'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/conflict'
         default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/default'
     delete:
       tags:
         - Asset Administration Shell Basic Discovery API
@@ -152,9 +131,9 @@ paths:
         '204':
           description: Specific Asset identifiers deleted successfully
         '404':
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/not-found'
         default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/default'
   /description:
     get:
       tags:
@@ -169,6 +148,6 @@ paths:
           content:
             application/json:
               schema:
-                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/ServiceDescription'
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/schemas/ServiceDescription'
         default:
-          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.3#/components/responses/default'
diff --git a/DiscoveryServiceSpecification/V3.1_SSP-001.yaml b/DiscoveryServiceSpecification/V3.1_SSP-001.yaml
@@ -0,0 +1,174 @@
+openapi: 3.0.3
+info:
+  title: DotAAS Part 2 | HTTP/REST | Discovery Service Specification (V3.1 Draft, not released)
+  description: >-
+    The entire Full Profile of the Discovery Service Specification as part of the [Specification of the Asset Administration Shell - Part 2: API](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).  
+    
+    Publisher: Industrial Digital Twin Association (IDTA) January 2025
+  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.1.0_SSP-001
+  x-profile-identifier: https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001
+servers:
+- url: 'https://admin-shell.io/api/v3.1'
+- url: 'https://example.com/'
+
+paths:
+  /lookup/shells:
+    get:
+      deprecated: true
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Returns a list of Asset Administration Shell IDs linked to specific asset identifiers or the global asset ID
+      operationId: GetAllAssetAdministrationShellIdsByAssetLink
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellIdsByAssetLink/3/0
+      parameters:
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetIds'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
+      responses:
+        '200':
+          description: Requested Asset Administration Shell IDs
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
+                - type: object
+                  properties:
+                    result:
+                      type: array
+                      items:
+                        type: string
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+  /lookup/shellsByAssetLink:
+    post:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Returns a list of Asset Administration Shell IDs linked to specific asset identifiers or the global asset ID
+      operationId: SearchAllAssetAdministrationShellIdsByAssetLink
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/SearchAllAssetAdministrationShellIdsByAssetLink/3/1
+      parameters:
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Limit'
+        - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/Cursor'
+      requestBody:
+        description: A list of specific asset identifiers. Search for the global asset ID is supported by setting "name"  to "globalAssetId" (see Constraint AASd-116).
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                '$ref': 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/AssetLink'
+      responses:
+        '200':
+          description: Requested Asset Administration Shell IDs
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
+                - type: object
+                  properties:
+                    result:
+                      type: array
+                      items:
+                        type: string
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+
+  /lookup/shells/{aasIdentifier}:
+    parameters:
+      - $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/parameters/AssetAdministrationShellIdentifier'
+    get:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Returns a list of specific asset identifiers based on an Asset Administration Shell ID to edit discoverable content. The global asset ID is returned as specific asset ID with "name" equal to "globalAssetId" (see Constraint AASd-116).
+      operationId: GetAllAssetLinksById
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/GetAllAssetLinksById/3/0
+      responses:
+        '200':
+          description: Requested specific Asset identifiers (including the global asset ID represented by a specific asset ID)
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+    post:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Creates specific asset identifiers linked to an Asset Administration Shell to edit discoverable content
+      operationId: PostAllAssetLinksById
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/PostAllAssetLinksById/3/0
+      requestBody:
+        description: A set of specific asset identifiers
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+        required: true
+      responses:
+        '201':
+          description: Specific asset identifiers created successfully
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/SpecificAssetId'
+        '400':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+        '409':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/conflict'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
+    delete:
+      tags:
+        - Asset Administration Shell Basic Discovery API
+      summary: Deletes specified specific asset identifiers linked to an Asset Administration Shell: discovery via these specific asset IDs shall not be supported any longer
+      operationId: DeleteAllAssetLinksById
+      x-semanticIds:
+        - https://admin-shell.io/aas/API/DeleteAllAssetLinksById/3/0
+      responses:
+        '204':
+          description: Specific asset identifiers deleted successfully
+        '404':
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/not-found'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.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/0
+      responses:
+        '200':
+          description: Requested Description
+          content:
+            application/json:
+              schema:
+                $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/ServiceDescription'
+        default:
+          $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/default'
diff --git a/DiscoveryServiceSpecification/V3.1_SSP-002.yaml b/DiscoveryServiceSpecification/V3.1_SSP-002.yaml
