asyncapi: 2.0.0
info:
  version: 3.0.2
  x-visibility: external
  title: MindConnect OPC UA PubSub API
  description: |
    The MindConnect OPC UA PubSub API provides messaging operations for device agents to define their asset or event models and to upload data accordingly stored as either asset timeseries data or events.

    The communication protocol is based on the OPC UA PubSub Spec Part 14 Release 1.04. Additional restrictions are described in the message schemas of this API spec. For the full message schemas refer to the mentioned OPC UA PubSub standard documentation.

    The asset model as well as event model is defined using the same OPC UA PubSub message types. The uploading of timeseries data according to the asset model and the creation of event instances also is based on the same OPC UA PubSub message types. The concrete conversion to either asset and timeseries data or to event types and instances is chosen by the client by publishing to the corresponding message topics. The mappings from OPC UA PubSub message to MindSphere data model are described in the accompanying documents of this service in the MindSphere Developer Documentation. Note that, in order to upload timeseries data first a corresponding asset model must be defined. Similarly, to upload event data first a corresponding event model must be defined.


    The API currently works with:
    * the MQTT messaging protocol
    * OPC UA PubSub UADP Message mappings

    Limitations:
    * The number of publishers and structure definitions per tenant is limited.
    * There is an upload frequency limit per tenant for meta and data message packages.
    * The size of network message is limited.
    * The number of data set writer id, configuration version, field and key value pair count per publisher are limited.
    * The size of hierarchy level is limited per data point.

    Please see the MindConnect OPC UA PubSub section in the MindSphere Developer Documentation page to get more details.

servers:
  MQTT:
    url: 'mqtt.{region}.mindsphere.io:8883'
    description: |
      One of the two alternative brokers for agent connection. Detailed information on the MindSphere MQTT Broker can be found in the page Connecting to OPC UA PubSub Service via MQTT, part of the "APIs & Services / OPC UA PubSub Service" section of the MindSphere Developer Documentation.
    protocol: mqtt
    variables:
      region:
        description: |
          Defines in which area it works.
  MindconnectMQTT:
    url: 'mindconnectmqtt.{region}.mindsphere.io:8883'
    description: |
      One of the two alternative brokers for agent connection. Detailed information on the MindSphere MQTT Broker can be found in the page MindConnect MQTT API section of the MindSphere Developer Documentation.
    protocol: mqtt
    variables:
      region:
        description: |
          Defines in which area it works.

channels:
  c/{clientId}/o/opcua/v3/u/m/t:
    parameters:
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      description: |
        Define asset model, based on OPC UA PubSub MetaDataMessage.
      tags:
        - name: Timeseries Operations
      message:
        summary: Metadata of Timeseries Messages
        $ref: '#/components/messages/MetaData'

  c/{clientId}/o/opcua/v3/u/d/t:
    parameters:
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      description: |
        Upload timeseries data according to defined asset model, based on OPC UA PubSub DataSetMessage.
      tags:
        - name: Timeseries Operations
      message:
        summary: Data of Timeseries Messages
        $ref: '#/components/messages/DataSetMessage'

  c/{clientId}/o/opcua/v3/u/m/e:
    parameters:
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      description: |
        Define event model, based on OPC UA PubSub MetaDataMessage.
      tags:
        - name: Event Operations
      message:
        summary: Metadata of Event Messages
        $ref: '#/components/messages/MetaData'

  c/{clientId}/o/opcua/v3/u/d/e:
    parameters:
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      description: |
        Upload event data according to defined event model, based on OPC UA PubSub DataSetMessage.
      tags:
        - name: event
      message:
        summary: Event Operations
        $ref: '#/components/messages/DataSetMessage'

components:
  messages:
    MetaData:
      description: |
        Contains data model of publisher as OPC UA PubSub NetworkMessage specified as MetaDataMessage. The following OPC UA Message types have to be used:

        - NetworkMessage
          - DiscoveryMessage
            - DiscoveryResponse
              - MetaDataMessage

        This message can be used to either create a MindSphere asset model or to create a MindSphere event model, depending on the operation used.

        The message schemas only describe differences to the original OPC UA PubSub specification. The full schema is defined in the OPC UA PubSub specification.

      headers:
        type: object
        properties:
          networkMessageHeader:
            $ref: '#/components/schemas/NetworkMessageHeader'
      payload:
        $ref: '#/components/schemas/NetworkMessageMetadata'

    DataSetMessage:
      description: |
        Upload data values as OPC UA PubSub NetworkMessage specified as DataSetMessage. The following OPC UA Message types have to be used:

        - NetworkMessage
          - DataSetMessage
            - DataKeyFrame DataSetMessage
        - NetworkMessage
          - DataSetMessage
            - DataDeltaFrame DataSetMessage

        The provided data values are either stored as timeseries data or as event instances, depending on the operation used.

        The message schemas only describe differences to the original OPC UA PubSub specification. The full schema is defined in the OPC UA PubSub specification.
      headers:
        type: object
        properties:
          networkMessageHeader:
            $ref: '#/components/schemas/NetworkMessageHeader'
      payload:
        $ref: '#/components/schemas/NetworkMessageDataSetMessage'
        format: binary

  schemas:
    NetworkMessageHeader:
      description: Fields of NetworkMessageHeaders need to be align with the spec.
      type: object
      required:
       - publisherId
      properties:
        publisherId:
          type: string
          example: PublisherId-123
          maximum: 128
          minimum: 1
          description: publisherId represents owner of the NetworkMessage

    NetworkMessageDataSetMessage:
      properties:
        payload:
          type: object
          properties:
            messages:
              type: object
              properties:
                dataSetMessageHeader:
                  type: object
                  properties:
                    timestamp:
                      description: If a "timestamp" field (for event message) or a "_time" field (for timeseries message) are not present in payload, this field is used as the timestamp of message.
                      type: object

                dataSetMessage:
                  type: array


    NetworkMessageMetadata:
      properties:
        payload:
          type: object
          properties:
            messages:
              type: object
              properties:
                discoveryResponseMessage:
                  type: object
                  properties:
                    metaData:
                      type: object
                      properties:
                        fields:
                          type: array
                          items:
                            type: object
                            properties:
                              dataType:
                                description:
                                  Id of object type of the instance, 4-byte NodeId is
                                  allowed.
                                format: NodeId
                                type: object
                        structureDataTypes:
                          type: array
                          items:
                            type: object
                            properties:
                              structureDefinition:
                                type: object
                                properties:
                                  baseDataType:
                                    description: Id of object type, 4-byte NodeId is allowed.
                                    format: NodeId
                                    type: object
                                  fields:
                                    description: List of variables
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        dataType:
                                          description:
                                            Primitive type of the variable, 4-byte
                                            NodeId is allowed.
                                          type: object
                                          format: nodeId



  parameters:
    ClientId:
      description:
        See the MindSphere Developer Documentation overview page for this API to get more details.
      schema:
        type: string
        example: ClientId-123
