# Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH, Germany. All rights reserved.
asyncapi: 3.0.0
info:
  title: Digital Twin Registry - Async API
  version: ""
  description: |
    The BCI Digital Twin Registry Async API allows you to produce
    commands to your Digital Twin Registry tenant in an asynchronous 
    manner and consume the corresponding responses from the response
    topic.
  license:
    name: Copyright
  contact:
    name: Download YAML
    url: api-doc-async.yaml

defaultContentType: application/json

channels:
  command:
    address: registry.{tenant_id}.api.command.json
    description: Digital Twin Registry Command topic
    messages:
      createTwinV1.message:
        $ref: '#/components/messages/createTwinV1'
      createShellV1.message:
        $ref: '#/components/messages/createShellV1'
  response:
    address: registry.{tenant_id}.api.response.json
    description: Digital Twin Registry Response topic
    messages:
      entityCreatedV1.message:
        $ref: '#/components/messages/entityCreatedV1'
      errorResponseV1.message:
        $ref: '#/components/messages/errorResponseV1'
operations:
  commandSend:
    action: send
    channel:
      $ref: '#/channels/command'
    messages:
      - $ref: '#/channels/command/messages/createTwinV1.message'
      - $ref: '#/channels/command/messages/createShellV1.message'
  responseReceive:
    action: receive
    channel:
      $ref: '#/channels/response'
    messages:
      - $ref: '#/channels/response/messages/entityCreatedV1.message'
      - $ref: '#/channels/response/messages/errorResponseV1.message'
components:
  messages:
    createTwinV1:
      name: CreateTwinV1
      title: Create a single Twin
      headers:
        type: object
        description: Kafka headers
        properties:
          schema-name:
            type: "string"
            description: "The name of the Schema we are using"
            const: "CreateTwin:v1"
          correlation-id:
            $ref: '#/components/schemas/CorrelationId'
        required:
          - schema-name
          - correlation-id
        additionalProperties: true
      payload:
        $ref: '#/components/schemas/CreateTwinV1'
      tags:
        - $ref: '#/components/tags/Command'
        - $ref: '#/components/tags/Create'
        - $ref: '#/components/tags/Twins'
    createShellV1:
      name: CreateShellV1
      title: Create a single Shell
      headers:
        type: object
        description: Kafka headers
        properties:
          schema-name:
            type: "string"
            description: "The name of the Schema we are using"
            const: "CreateShell:v1"
          correlation-id:
            $ref: '#/components/schemas/CorrelationId'
        required:
          - schema-name
          - correlation-id
        additionalProperties: true
      payload:
        $ref: '#/components/schemas/CreateShellV1'
      tags:
        - $ref: '#/components/tags/Command'
        - $ref: '#/components/tags/Create'
        - $ref: '#/components/tags/Shells'
    entityCreatedV1:
      name: EntityCreatedV1
      title: Successfully created entity
      headers:
        type: object
        description: Kafka headers
        properties:
          schema-name:
            type: "string"
            description: "The name of the Schema we are using"
            const: "EntityCreated:v1"
          correlation-id:
            $ref: '#/components/schemas/CorrelationId'
        required:
          - schema-name
          - correlation-id
        additionalProperties: true
      payload:
        $ref: '#/components/schemas/EntityCreatedV1'
      tags:
        - $ref: '#/components/tags/Response'
        - $ref: '#/components/tags/Success'
    errorResponseV1:
      name: ErrorResponseV1
      title: Failed operation
      headers:
        type: object
        description: Kafka headers
        properties:
          schema-name:
            type: "string"
            description: "The name of the Schema we are using"
            const: "ErrorResponse:v1"
          correlation-id:
            $ref: '#/components/schemas/CorrelationId'
        required:
          - schema-name
          - correlation-id
        additionalProperties: true
      payload:
        $ref: '#/components/schemas/ErrorResponseV1'
      tags:
        - $ref: '#/components/tags/Response'
        - $ref: '#/components/tags/Failure'
  schemas:
    CorrelationId:
      type: string
      description: A unique Id identifying the message. This will be included as-is in the corresponding response message. We recommend using a well established ID format like UUID or Snowflake ID to ensure uniqueness.
      pattern: '[0-9a-zA-Z\-_:]{1,128}'
      maxLength: 128
      minLength: 1
      examples:
        - "e44d286e-afe3-4d88-b5cd-c32ad9e95965"
    EntityIdV1:
      type: integer
      format: int64
      description: Internal unique id of an entity which will be set by the service. A nil ID value of '0L' is reserved for resolved virtual Aspects or HTTP endpoints.
      readOnly: true
      examples:
        - 5821
    DigitalTwinKindV1:
      type: string
      enum:
        - TYPE
        - INSTANCE
        - ROLE
        - NOT_APPLICABLE
      description: Kind of the Twin
      examples:
        - "INSTANCE"
    EntityCreatedV1:
      type: object
      description: Created a single Entity v1
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/EntityIdV1'
      additionalProperties: false
    ErrorResponseV1:
      type: object
      description: There was an error while performing the operation
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorV1'
      additionalProperties: false
    ErrorV1:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          examples:
            - "Validation failed"
          description: The detailed error message for the exception which occurred.
          minLength: 1
        details:
          type: object
          description: An object with key/value pairs containing additional information about the error.
          examples:
            - "name": "size must be between 1 and 128"
              "description": "size must be between 1 and 512"
        code:
          type: string
          description: A machine processable, application internal error code.
          minLength: 1
          examples:
            - 20001
      additionalProperties: false
    CreateTwinV1:
      type: object
      description: Create a single Twin v1
      required:
        - localIdentifiers
      properties:
        twinType:
          type: string
          description: The type of the Twin
          maxLength: 128
          examples:
            - "Bosch Nexo cordless Wi-Fi nutrunner"
        twinCategory:
          type: string
          description: The category of the Twin
          maxLength: 128
          examples:
            - "Drill"
        description:
          type: string
          description: Detailed description of the Twin
          maxLength: 4000
          examples:
            - "On Nexo the complete control unit is in the nutrunner – the first of its kind."
        manufacturer:
          type: string
          description: Manufacturer of the physical asset represented by the Twin
          maxLength: 128
          examples:
            - "Bosch"
        localIdentifiers:
          type: array
          description: Local Identifiers of the Twin
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LocalIdentifierCreateV1'
          maxItems: 10
          minItems: 1
        labels:
          type: array
          description: Labels of the Twin
          uniqueItems: true
          items:
            type: string
            examples:
              - "cordless-drills"
          maxItems: 10
        groups:
          type: array
          description: Twin Groups in which the Twin shall be a member.
          uniqueItems: true
          items:
            $ref: '#/components/schemas/EntityIdV1'
          maxItems: 50
        twinKind:
          $ref: '#/components/schemas/DigitalTwinKindV1'
      additionalProperties: false
    LocalIdentifierCreateV1:
      type: object
      required:
        - localIdentifierKeyPairs
      properties:
        localIdentifierKeyPairs:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LocalIdentifierKeyPairCreateV1'
          maxItems: 5
          minItems: 1
      description: Specific Local Identifier from the list of the Twin
      additionalProperties: false
    LocalIdentifierKeyPairCreateV1:
      type: object
      required:
        - value
        - key
      properties:
        key:
          type: string
          description: Local Identifier key
          minLength: 1
          maxLength: 64
          examples:
            - "serialNumber"
        value:
          type: string
          description: Local Identifier value
          minLength: 1
          maxLength: 128
          examples:
            - "123456"
      description: Specify the key and values of the Local Identifier
      additionalProperties: false
    CreateShellV1:
      type: object
      description: Create a single Shell v1
      required:
        - id
      properties:
        description:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LangStringTextTypeV1'
        displayName:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LangStringNameTypeV1'
        assetKind:
          $ref: '#/components/schemas/AssetKindV1'
        assetType:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
        globalAssetId:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
        idShort:
          minLength: 1
          maxLength: 128
          type: string
          description: The idShort is unique.
        id:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
          examples:
            - 'https://example.org/aas/motor'
        specificAssetIds:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/SpecificAssetIdV1'
        submodelDescriptors:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/SubmodelDescriptorV1'
        groups:
          type: array
          description: Shell Groups
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ShellGroupIdDtoV1'
          maxItems: 50
        labels:
          type: array
          description: Labels of the Shell
          uniqueItems: true
          maxItems: 10
          items:
            type: string
        createdAt:
          description: Creation date. The format of parameter is RFC3339 (https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).
          type: string
          format: date-time
          examples:
            - '2021-03-05T12:34:56.123Z'
      additionalProperties: false
    LangStringTextTypeV1:
      required:
        - language
        - text
      type: object
      properties:
        language:
          pattern: "^(([a-zA-Z]{2,3}(-[a-zA-Z]{3}(-[a-zA-Z]{3}){0,2})?|[a-zA-Z]{4}|[a-zA-Z]{5,8})(-[a-zA-Z]{4})?(-([a-zA-Z]{2}|[0-9]{3}))?(-(([a-zA-Z0-9]){5,8}|[0-9]([a-zA-Z0-9]){3}))*(-[0-9A-WY-Za-wy-z](-([a-zA-Z0-9]){2,8})+)*(-[xX](-([a-zA-Z0-9]){1,8})+)?|[xX](-([a-zA-Z0-9]){1,8})+|((en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang)))$"
          type: string
          examples:
            - 'en'
        text:
          minLength: 1
          maxLength: 1023
          type: string
      additionalProperties: false
    LangStringNameTypeV1:
      required:
        - language
        - text
      type: object
      properties:
        language:
          pattern: "^(([a-zA-Z]{2,3}(-[a-zA-Z]{3}(-[a-zA-Z]{3}){0,2})?|[a-zA-Z]{4}|[a-zA-Z]{5,8})(-[a-zA-Z]{4})?(-([a-zA-Z]{2}|[0-9]{3}))?(-(([a-zA-Z0-9]){5,8}|[0-9]([a-zA-Z0-9]){3}))*(-[0-9A-WY-Za-wy-z](-([a-zA-Z0-9]){2,8})+)*(-[xX](-([a-zA-Z0-9]){1,8})+)?|[xX](-([a-zA-Z0-9]){1,8})+|((en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang)))$"
          type: string
          examples:
            - 'en'
        text:
          minLength: 1
          maxLength: 128
          type: string
      additionalProperties: false
    AssetKindV1:
      type: string
      enum:
        - Instance
        - NotApplicable
        - Role
        - Type
      additionalProperties: false
    SpecificAssetIdV1:
      type: object
      required:
        - name
        - value
      properties:
        semanticId:
          $ref: '#/components/schemas/ReferenceV1'
        supplementalSemanticIds:
          maxItems: 50
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ReferenceV1'
        name:
          maxLength: 64
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
          examples:
            - 'manufacturerId'
        value:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
          examples:
            - 'BOSCH'
        externalSubjectId:
          $ref: '#/components/schemas/ReferenceV1'
      additionalProperties: false
    SubmodelDescriptorV1:
      required:
        - endpoints
        - id
      type: object
      properties:
        endpoints:
          minItems: 1
          maxItems: 10000
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/EndpointV1'
        idShort:
          minLength: 1
          maxLength: 128
          type: string
          description: The idShort is not unique overall. All Submodel idShort in one Shell are unique.
        id:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
          examples:
            - 'https://admin-shell.io/zvei/nameplate/1/0/Nameplate'
        semanticId:
          $ref: '#/components/schemas/ReferenceV1'
        supplementalSemanticId:
          maxItems: 50
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ReferenceV1'
        description:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LangStringTextTypeV1'
        displayName:
          type: array
          maxItems: 50
          uniqueItems: true
          items:
            $ref: '#/components/schemas/LangStringNameTypeV1'
      additionalProperties: false
    ShellGroupIdDtoV1:
      type: object
      description: Identification of an Shell Group
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/EntityIdV1'
      additionalProperties: false
    ReferenceV1:
      required:
        - keys
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ReferenceTypesV1'
        keys:
          minItems: 1
          maxItems: 50
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/KeyV1'
        referredSemanticId:
          $ref: '#/components/schemas/ReferenceParentV1'
      additionalProperties: false
    ReferenceParentV1:
      required:
        - keys
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ReferenceTypesV1'
        referredSemanticId:
          $ref: '#/components/schemas/ReferenceV1'
        keys:
          minItems: 1
          maxItems: 50
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/KeyV1'
      additionalProperties: false
    ReferenceTypesV1:
      type: string
      enum:
        - ExternalReference
        - ModelReference
      additionalProperties: false
    KeyV1:
      required:
        - type
        - value
      type: object
      properties:
        type:
          $ref: '#/components/schemas/KeyTypesV1'
        value:
          maxLength: 2000
          minLength: 1
          pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
          type: string
          examples:
            - 'M001'
      additionalProperties: false
    KeyTypesV1:
      type: string
      enum:
        - AnnotatedRelationshipElement
        - AssetAdministrationShell
        - BasicEventElement
        - Blob
        - Capability
        - ConceptDescription
        - DataElement
        - Entity
        - EventElement
        - File
        - FragmentReference
        - GlobalReference
        - Identifiable
        - MultiLanguageProperty
        - Operation
        - Property
        - Range
        - Referable
        - ReferenceElement
        - RelationshipElement
        - Submodel
        - SubmodelElement
        - SubmodelElementCollection
        - SubmodelElementList
      additionalProperties: false
    EndpointV1:
      required:
        - interface
        - protocolInformation
      type: object
      properties:
        interface:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'AAS-3.0'
        protocolInformation:
          $ref: '#/components/schemas/ProtocolInformationV1'
      additionalProperties: false
    ProtocolInformationV1:
      required:
        - href
      type: object
      properties:
        href:
          minLength: 1
          maxLength: 2048
          type: string
          examples:
            - 'https://localhost:1234/api/v3.0/aas'
            - 'opc.tcp://localhost:4840'
            - 'https://localhost:5678'
        endpointProtocol:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'HTTP'
        endpointProtocolVersion:
          type: array
          uniqueItems: true
          items:
            minLength: 1
            maxLength: 128
            type: string
            examples:
              - '1.1'
        subprotocol:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'OPC UA Basic SOAP'
        subprotocolBody:
          minLength: 1
          maxLength: 2048
          type: string
          examples:
            - 'ns=2;s=MyAAS'
        subprotocolBodyEncoding:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'application/soap+xml'
        securityAttributes:
          maxItems: 100
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProtocolInformation_securityAttributesV1'
      additionalProperties: false
    ProtocolInformation_securityAttributesV1:
      required:
        - key
        - type
        - value
      type: object
      properties:
        type:
          $id: TypeEnum # avoid anonymous node (see https://github.com/asyncapi/java-spring-template/issues/131)
          type: string
          enum:
            - NONE
            - RFC_TLSA
            - W3C_DID
        key:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'securityKey'
        value:
          minLength: 1
          maxLength: 128
          type: string
          examples:
            - 'securityValue'
      additionalProperties: false
  tags:
    Response:
      name: Response
      description: Response
    Success:
      name: Success
      description: Successful operation
    Failure:
      name: Failure
      description: Failed operation
    Command:
      name: Command
      description: A command sent to the Digital Twin Registry
    Create:
      name: Create
      description: Create an entity
    Twins:
      name: Twins
      description: Digital Twins
    Shells:
      name: Shells
      description: Shell Descriptors