openapi: 3.0.3
info:
  title: DotAAS Part 2 | HTTP/REST | Submodel Registry Service Specification
  description: >-
    The Full Profile of the Submodel Registry Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).  

    Copyright: Industrial Digital Twin Association (IDTA) 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.2.0_SSP-001
  x-profile-identifier: https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-001
servers:
- url: 'https://admin-shell.io/api/v3/'
- url: 'https://example.com/'
paths:
  /submodel-descriptors:
    get:
      tags:
        - Submodel Registry API
      summary: Returns all Submodel Descriptors
      operationId: GetAllSubmodelDescriptors
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllSubmodelDescriptors/3/2
      parameters:
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested Submodel Descriptors
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/GetSubmodelDescriptorsResult'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'    
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    post:
      tags:
        - Submodel Registry API
      summary: Creates a new Submodel Descriptor, i.e. registers a submodel
      operationId: PostSubmodelDescriptor
      x-semanticIds:
        - https://admin-shell.io/aas/API/PostSubmodelDescriptor/3/2
      requestBody:
        description: Submodel Descriptor object
        content:
          application/json:
            schema:
              $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/SubmodelDescriptor'
        required: true
      responses:
        '201':
          description: Submodel Descriptor created successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/SubmodelDescriptor'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '409':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/conflict'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /submodel-descriptors/$recent-changes:
    get:
      tags:
        - Submodel Registry API
      summary: Returns all Submodel Descriptors that have been recently changed
      operationId: GetAllSubmodelDescriptorsRecentChanges
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllSubmodelDescriptorsRecentChanges/3/2
      parameters:
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/CreatedFrom'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/UpdatedFrom'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested Submodel Descriptors that have been recently changed
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/GetSubmodelDescriptorsResult'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /submodel-descriptors/{submodelIdentifier}:
    parameters:
      - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/SubmodelIdentifier'
    get:
      tags:
        - Submodel Registry API
      summary: Returns a specific Submodel Descriptor
      operationId: GetSubmodelDescriptorById
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetSubmodelDescriptorById/3/2
      responses:
        '200':
          description: Requested Submodel Descriptor
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/SubmodelDescriptor'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'    
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    put:
      tags:
        - Submodel Registry API
      summary: Creates or updates an existing Submodel Descriptor
      operationId: PutSubmodelDescriptorById
      x-semanticIds:
        - https://admin-shell.io/aas/API/PutSubmodelDescriptorById/3/2
      requestBody:
        description: Submodel Descriptor object
        content:
          application/json:
            schema:
              $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/SubmodelDescriptor'
        required: true
      responses:
        '201':
          description: Submodel Descriptor created successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/SubmodelDescriptor'
        '204':
          description: Submodel Descriptor updated successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'    
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    delete:
      tags:
        - Submodel Registry API
      summary: Deletes a Submodel Descriptor, i.e. de-registers a submodel
      operationId: DeleteSubmodelDescriptorById
      x-semanticIds:
        - https://admin-shell.io/aas/API/DeleteSubmodelDescriptorById/3/2
      responses:
        '204':
          description: Submodel Descriptor deleted successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetSelfDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetSelfDescription/3/2
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/ServiceDescription'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden' 
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'