asyncapi: 2.2.0
info:
  version: 3.0.0
  x-visibility: internal
  title: Asset Modeler Async API
  description: >
    Asset Modeler Async API defines topics and message structures to create
    their assets, types and mappings.


    Devices can send their own asset model or can instantiate already stored
    asset model.


    Models are templates describing asset/aspect types, asset instances, asset
    hierarchy and mappings from data point ids to variables in aspects.

    Instantiations are the realization of models. An instantiation job takes a
    model and creates the items described in the model by creating types,
    instances and mappings. A model can be instantiated many times.


    Models and instantiations are loosely coupled. A change to model
    instantiation does not affect model. Also a change in model does not affect
    any completed instantiations as well. For example, if a model is deleted,
    existing instantiations are not affected. Or moving an asset created by an
    instantiation, does not affect the model.


    Limitations:

    * The number of asset model definitions per tenant is limited.

    * There are frequency limits per tenant and per client for published and
    received messages.

    * Maximum size of body is 24KBs.
servers:
  PVT:
    url: '<dynamic>'
    description: |
      MQTT Broker for Insights Hub which offers below described topics.
    protocol: mqtt
channels:
  'tc/{tenantId}/{clientId}/o/amo_v3/m':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      operationId: createModel
      description: >
        Asset Model describing aspect types, asset types, asset instances and
        data point mappings.
      tags:
        - name: Asset Modelling Operations
      message:
        summary: Asset Model message.
        $ref: '#/components/messages/AssetModelMessage'
  'tc/{tenantId}/{clientId}/o/amo_v3/i':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    publish:
      operationId: instantiateModel
      description: |
        Create a new model with given asset model in body.
      tags:
        - name: Asset Modelling Operation
      message:
        summary: Instantiation Job message.
        $ref: '#/components/messages/InstantiationJobMessage'
  'tc/{tenantId}/{clientId}/i/amo_v3/ms':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    subscribe:
      description: |
        Receive model creation results for a previous model request.
      tags:
        - name: Asset Modelling Operation
      message:
        summary: Model Creation Result message.
        $ref: '#/components/messages/ModelStatusMessage'
  'tc/{tenantId}/{clientId}/i/amo_v3/ip':
    parameters:
      tenantId:
        $ref: '#/components/parameters/TenantId'
      clientId:
        $ref: '#/components/parameters/ClientId'
    subscribe:
      description: |
        Receive instantiation job results for a previous instantiation request.
      tags:
        - name: Asset Modelling Operation
      message:
        summary: Instantiation Job Result message.
        $ref: '#/components/messages/InstantiationJobStatusMessage'
components:
  messages:
    AssetModelMessage:
      name: Asset Model message
      description: >
        Structure containing models for asset/aspect types, asset instances and
        mappings from provided keys to variables in the specified model.
      payload:
        $ref: '#/components/schemas/ModelData'
    InstantiationJobMessage:
      name: Instanitate Model message
      description: |
        Message containing model instantiation request parameters.
      payload:
        $ref: '#/components/schemas/InstantiationData'
    ModelStatusMessage:
      name: Model Result message
      description: |
        Message containing result of a previous model creation request.
      payload:
        $ref: '#/components/schemas/ModelStatus'
    InstantiationJobStatusMessage:
      name: Instantiation Job Result message
      description: |
        Message containing results of a previous instantiation request.
      payload:
        $ref: '#/components/schemas/InstantiationJobStatus'
  schemas:
    InstantiationData:
      title: Instantiation
      type: object
      properties:
        id:
          type: string
          example: 99609765fed2452c8e126814c283a27f
          description: Unique id of message.
          minLength: 1
          maxLength: 32
        data:
          type: object
          $ref: '#/components/schemas/Instantiation'
          description: Structure containing properties for instantiation job.
      required:
        - id
        - data
    Instantiation:
      title: Instantiation
      type: object
      properties:
        modelId:
          type: string
          example: 89609765fed2452c8e126814c283a27f
          description: >-
            Id of the model to be instantiated. Either this or `modelExternalId` must be specified. If `modelId` is specified, `modelExternalId` is ignored.
        modelExternalId:
          type: string
          description: >-
            External id of the model to be instantiated. Either this, or `modelId` must be specified. If `modelId` is specified, `modelExternalId` is ignored.
          example: ElectricCarModel-001
        modelParentAssetId:
          type: string
          example: 8fd2f7db0d5b4613bb3eb801782cc33a
          description: >-
            Asset id of the asset that will be used as parent asset for the
            model. All asset instance models without a parent reference id in
            model will be direct child of this asset. If not provided, all asset
            instance models will be child of agent asset.
        parameterization:
          $ref: '#/components/schemas/ParameterizationValues'
          description: >-
            List of name and value for parameterized properties in specified
            model.
      required:
        - parameterization
    InstantiationJobStatus:
      title: InstantiationJobStatus
      type: object
      properties:
        id:
          type: string
          description: Unique id of message.
          readOnly: true
          example: 301a4a3989de4e8a93c3c2358870b39d
          minLength: 1
          maxLength: 32
        requestId:
          type: string
          description: >-
            Id of the message that triggered this instantiation job. This field
            can only be undefined if the message triggered this instantiation
            job was malformed (i.e. missing an id attribute).
          readOnly: true
          example: 99609765fed2452c8e126814c283a27f
          minLength: 1
          maxLength: 32
        data:
          type: object
          $ref: '#/components/schemas/InstantiationStatusData'
          description: Structure containing properties for instantiation job result.
      required:
        - id
        - data
    ModelStatus:
      title: ModelStatus
      type: object
      properties:
        id:
          type: string
          example: 69149765fed2452c8e126814c283a27f
          description: Unique id of message.
          minLength: 1
          maxLength: 32
        requestId:
          type: string
          readOnly: true
          example: 72609761sdv245248e126814c283a27f
          description: >-
            Id of model creation request message that triggered model creation.
            This field can only be undefined if the message that triggered model
            creation was malformed (i.e. missing an id attribute).
          minLength: 1
          maxLength: 32
        data:
          type: object
          $ref: '#/components/schemas/ModelStatusData'
      required:
        - id
        - data
    AssetTypeId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: '[A-Za-z0-9_]{1,8}\.[A-Za-z0-9_]+'
      description: >-
        The asset type's id is a unique identifier. The id's length must be
        between 1 and 128 characters and matches the following symbols "A-Z",
        "a-z", "0-9", "_" and "." beginning with the tenant prefix what has a
        maximum of 8 characters. (e.g . ten_pref.type_id). Once set cannot be
        changed.
      example: mdsp.spaceship
    AspectTypeId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: '[A-Za-z0-9_]{1,8}\.[A-Za-z0-9_]+'
      description: >-
        The aspect type's id is a unique identifier. The id's length must be
        between 1 and 128 characters and matches the following symbols "A-Z",
        "a-z", "0-9", "_" and "." beginning with the tenant prefix what has a
        maximum of 8 characters. (e.g . ten_pref.type_id). Once set cannot be
        changed.
      example: mdsp.wing
    VariableDefinition:
      type: object
      required:
        - name
        - dataType
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: '[a-zA-Z_][a-zA-Z0-9_]*'
          description: >-
            Name of the variable. Once set cannot be changed. Reserved words
            (id, name, description, tenant, etag, scope, properties,
            propertySets, extends, variables, aspects, parentTypeId) cannot be
            used as variable names.
          example: temperature
        dataType:
          type: string
          enum:
            - BOOLEAN
            - INT
            - LONG
            - DOUBLE
            - STRING
            - TIMESTAMP
            - BIG_STRING
          description: >-
            Data type of the variable. BIG_STRING could only be used by
            variables in dynamic aspect-types. Cannot be changed.
          example: STRING
        unit:
          type: string
          maxLength: 32
          pattern: '[^\'']*'
          description: Unit of measurement. Cannot be changed.
          example: C/F
        searchable:
          type: boolean
          default: false
          description: >-
            Indicates whether sorting and filtering is allowed on this variable.
            Only usable for static properties. Cannot be changed.
          example: true
        length:
          type: integer
          minimum: 1
          maximum: 100000
          description: >-
            The max length of the variable's value. The length field is only
            used for variables of string or big_string dataType. Max length for
            string is 255 and max length for big_string 100000. Cannot be
            changed.
          example: 5
        defaultValue:
          type: string
          minLength: 1
          maxLength: 255
          description: The default value of the variable. It must be compatible with the dataType! The default value will be inherited by the asset type's child types and by the asset instantiating it. It can be defined in aspect types and asset types.
          example: 25/77

    AspectVariable:
      type: object
      allOf:
        - $ref: '#/components/schemas/VariableDefinition'
        - properties:
            qualityCode:
              type: boolean
              default: false
              description: >-
                Indicates whether the variable has quality code. Cannot be
                changed.
              example: true
    AspectType:
      title: AspectType
      type: object
      description: ''
      properties:
        id:
          $ref: '#/components/schemas/AspectTypeId'
        name:
          type: string
          description: >-
            Name of the aspect type. It has to be unique inside the tenant and
            cannot be changed later.
          pattern: '^[a-zA-Z0-9_]+'
          minLength: 1
          maxLength: 128
          example: '${aspectTypeName}'
        category:
          type: string
          enum:
            - static
            - dynamic
          description: >-
            If the aspect-type is used for static data or time-series. Cannot be
            changed once the aspect-type is created.
        scope:
          type: string
          enum:
            - public
            - private
          default: private
          example: private
          description: >-
            Visibility of aspect type. Setting this property to public makes it
            available to other tenants. Private types are only visible to the
            user's own tenant. Currently only private types can be created.
        variables:
          type: array
          description: >-
            Variables of the aspect-type. Variable names should be unique inside
            an aspect-type. Once a variable is added to the aspect that it
            cannot be renamed or removed. Only variables of static aspect-type
            can have default values.
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/AspectVariable'
        description:
          type: string
          description: The description of the aspect type
          example: wing aspect type description
        referenceId:
          type: string
          description: Reference id of this aspect type.
          example: 287adc1a086840e0a6721dfd1170e97c
      required:
        - id
        - name
        - category
        - variables
    AspectInstance:
      title: AspectInstance
      type: object
      properties:
        name:
          type: string
          description: >-
            Name of the aspect. It has to be unique inside the type-family
            (ancestors and descendants).Cannot be changed. Reserved words (id,
            name, description, tenant, etag, scope, properties, propertySets,
            extends, variables, aspects, parentTypeId) cannot be used as aspect
            names.
          minLength: 1
          maxLength: 64
          pattern: '[a-zA-Z0-9_]+'
          example: wingAspect
        aspectTypeId:
          $ref: '#/components/schemas/AspectTypeId'
      required:
        - name
        - aspectTypeId
    AssetType:
      title: AssetType
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AssetTypeId'
        name:
          type: string
          description: The type’s name.
          pattern: '[\p{L}_0-9_\. -]+'
          minLength: 1
          maxLength: 128
          example: wingAssetTypeName
        parentTypeId:
          type: string
          description: >-
            The asset type’s id is a unique identifier. The id’s length must be
            between 1 and 128 characters and matches the following symbols
            "A-Z", "a-z", "0-9", “_” and “.” beginning with the tenant prefix
            what has a maximum of 8 characters. (e.g . ten_pref.type_id). Once
            set cannot be changed.
          example: core.basicasset
          minLength: 1
          maxLength: 128
          pattern: '[A-Za-z0-9_]{1,8}\.[A-Za-z0-9_]+'
        aspects:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/AspectInstance'
        description:
          type: string
          description: description
          maxLength: 255
          example: Hyperspace jump capable space ship
        instantiable:
          type: boolean
          default: true
          example: true
          description: >-
            If instances can be created from this type. A non-instantiable type
            could be changed to be instantiable but not the other way around.
        scope:
          type: string
          enum:
            - public
            - private
          default: private
          example: private
          description: >-
            Visibility of the asset type. Setting this property to public makes
            it available to other tenants. Private types are only visible to the
            user's own tenant. Currently only private types could be created.
        referenceId:
          type: string
          description: Reference id of this asset type.
          example: 82a4cc2a69cc42af80c1c6cf5dbefde5
        variables:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/VariableDefinition'
      required:
        - id
        - name
        - parentTypeId
    TypeModel:
      title: Type Model
      type: object
      description: 'Model containing asset type and aspect type specifications. '
      properties:
        aspectTypes:
          type: array
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/AspectType'
        assetTypes:
          type: array
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/AssetType'
      required:
        - aspectTypes
        - assetTypes
    AssetDescription:
      title: Asset Description
      type: object
      x-tags:
        - Instance Model Jobs
      description: Model describing a single asset instance.
      properties:
        referenceId:
          type: string
          description: >-
            An id unique per instance model which can be used to refer to this
            asset from other places within this model.
          example: wingAssetReference
        parentReferenceId:
          type: string
          description: >-
            Reference id of the asset within this model. If not specified, this
            asset instance is created under model parent asset.
          example: root
        typeId:
          $ref: '#/components/schemas/AssetTypeId'
        name:
          type: string
          description: Name of the asset to be created.
          pattern: '[^\/\\]*'
          minLength: 1
          maxLength: 128
          example: wingAsset
        description:
          type: string
          description: The description of the asset
          maxLength: 255
          example: The ship of Han Solo and Chewbacca
      required:
        - referenceId
        - typeId
        - name
    InstanceModel:
      title: Instance Model
      type: object
      description: Model containing asset specifications.
      properties:
        assets:
          type: array
          minItems: 0
          maxItems: 100
          description: List of assets to be created.
          items:
            $ref: '#/components/schemas/AssetDescription'
      required:
        - assets
    Model:
      title: Model
      type: object
      description: >-
        Structure containing models for asset/aspect types, asset instances and
        mappings from provided keys to variables in the specified model.
      properties:
        externalId:
          type: string
          example: ElectricCarModel-001
          description: >-
            External id of the model. Models can be instantiated using id of
            model resource. But it is also possible to create a model resources
            with an external id and instantiate the model using with this
            external id without knowing generated id of a model resource.
        typeModel:
          $ref: '#/components/schemas/TypeModel'
        instanceModel:
          $ref: '#/components/schemas/InstanceModel'
        mappingModel:
          $ref: '#/components/schemas/MappingModel'
      required:
        - typeModel
        - instanceModel
        - mappingModel
        - externalId
    ModelData:
      title: ModelData
      type: object
      description: >-
        Structure containing models for asset/aspect types, asset instances and
        mappings from provided keys to variables in the specified model.
      properties:
        id:
          type: string
          example: 72609761sdv245248e126814c283a27f
          description: Unique id of message.
          minLength: 1
          maxLength: 32
        data:
          $ref: '#/components/schemas/Model'
      required:
        - id
        - data
    ModelStatusData:
      title: ModelStatusData
      type: object
      description: Structure containing identifiers of model and status of model creation.
      properties:
        id:
          type: string
          example: 89609765fed2452c8e126814c283a27f
          description: >-
            Unique id of model. This field can be undefined if job creation
            failed.
          minLength: 1
          maxLength: 32
        externalId:
          type: string
          readOnly: true
          example: ElectricCarModel-001
          description: >-
            External id of the model. This field can be undefined if job
            creation failed.
        status:
          type: string
          readOnly: true
          example: Failed
          enum:
            - Success
            - Failed
          description: Status of model creation request.
        errors:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            Error messages about this model creation. This field can only be
            undefined if model creation has been successfully completed.
          items:
            $ref: '#/components/schemas/ModelError'
          readOnly: false
      required:
        - status
    ParameterizationValues:
      title: Parameterization Model
      type: object
      properties:
        values:
          type: array
          minItems: 0
          maxItems: 100
          description: List of parameter name-value pairs for parameterizing the model.
          items:
            $ref: '#/components/schemas/ParameterizationValue'
      required:
        - values
    ParameterizationValue:
      title: Parameterization Info
      type: object
      description: Structure containing parameter name and its value.
      properties:
        name:
          type: string
          example: aspectTypeName
          minLength: 1
          maxLength: 128
        value:
          type: string
          example: wingAspectType
          minLength: 1
          maxLength: 128
      required:
        - name
        - value
    InstantiationStatusData:
      title: InstantiationStatusData
      type: object
      description: >-
        Structure containing identifiers of instantiation and status of
        instantiation job.
      properties:
        id:
          type: string
          example: 59609765fed2452c8e126814c283a27f
          description: >-
            Id of instantiation job created. This field can be undefined if job
            creation failed.
        modelId:
          type: string
          example: 89609765fed2452c8e126814c283a27f
          description: Id of the model. This field can be undefined if job creation failed.
        modelExternalId:
          type: string
          readOnly: true
          example: ElectricCarModel-001
          description: >-
            External id of the model. This field can be undefined if job
            creation failed.
        message:
          type: string
          readOnly: true
          example: 100% completed.
          description: Message about current status of request.
        status:
          type: string
          enum:
            - Success
            - InProgress
            - Failed
          readOnly: true
        errors:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            Error messages about this intantiation job. This field contains errors related to instantiation job creation and instantiation progress.
          items:
            $ref: '#/components/schemas/InstantiationError'
          readOnly: false
      required:
        - message
        - status
    Mapping:
      title: Mapping
      example:
        dataPointId: "dp01"
        assetReferenceId : "wingAssetReference"
        aspectName: "wingAspect"
        variableName: "temperature"
        referenceId: "19e9048e78f540e7a9ba25e1249fea9b"
      type: object
      description: >-
        Describes a key-value mapping where key is specified with key and
        value(destination) is specified by
        assetReferenceId/aspectName/variableName tuple.
      properties:
        dataPointId:
          type: string
          description: Mapping key of this mapping.
          example: dp01
        assetReferenceId:
          type: string
          description: >-
            Unique identifier of data asset. If `assetId` is provided,
            `assetReferenceId` will be ignored. This datapoint will be mapped for this `assetId`.
          example: wingAssetReference
        assetId:
          type: string
          description: >-
            Unique identifier of data asset. If `assetId` is provided,
            `assetReferenceId` will be ignored. This datapoint will be mapped for this `assetId`.
          example: 30d88a9a71d711eb94390242ac130002
        aspectName:
          type: string
          description: Name of the aspect within destination asset.
          example: "wingAspect"
        variableName:
          type: string
          description: Name of variable within destination aspect.
          example: temperature
        referenceId:
          type: string
          description: Reference id of this mapping
      required:
        - dataPointId
        - aspectName
        - variableName
    MappingModel:
      title: MappingModel
      type: object
      description: >-
        Model consisting of a list of mappings from keys to variables residing
        in a specific asset instance's aspect.
      properties:
        mappings:
          type: array
          minItems: 0
          maxItems: 1000
          items:
            $ref: '#/components/schemas/Mapping'
      required:
        - mappings
    ModelError:
      title: Model Error
      type: object
      description: Error response body model.
      properties:
        code:
          type: string
          description: Insights Hub error code
          example: mdsp.core.generic.invalidRequestBodyProperty
        logref:
          type: string
          description: CorrelationId of message
          example: ff4e48ff-0dbc-40d0-8ffd-9a7a8188d82a
        message:
          type: string
          description: Error message description
          example: >-
            Provided request body property {aspectVariable.dataType} must be [
            BOOLEAN, INT, LONG, DOUBLE, STRING, TIMESTAMP, BIG_STRING ]
    InstantiationError:
      title: Instantiation Error
      type: object
      description: Error response body model.
      properties:
        code:
          type: string
          description: Insights Hub error code
          example: mdsp.core.generic.invalidRequestBodyProperty
        logref:
          type: string
          description: CorrelationId of message
          example: ff4e48ff-0dbc-40d0-8ffd-9a7a8188d82a
        message:
          type: string
          description: Error message description
          example: >-
            {aspectType.id} matches the following symbols \"A-Z\", \"a-z\",
            \"0-9\", “_” and “.” beginning with the tenant prefix what has a
            maximum of 8 characters. (e.g . ten_pref.type_id)"
        referenceId:
          type: string
          description: >-
            Reference id of instantiated resource.
          example: 19e9048e78f540e7a9ba25e1249fea9b
  parameters:
    ClientId:
      description: >-
        MQTT client id. See the Insights Hub Developer Documentation overview page
        for this API to get more details.
      schema:
        type: string
        example: 201541ad38a4495a96e2021c762b647f_mytenant
    TenantId:
      description: >-
        Id of tenant which client belongs to. See the Insights Hub Developer
        Documentation overview page for this API to get more details.
      schema:
        type: string
        example: mytenant
