OpenApi-Implementation-View.yml

openapi: "3.0.3"
info:
  version: 0.2.7
  title: LNI 4.0 Edge Management REST API
  
  description: >-
    This API defines unified access methods for networked assets like edge devices, field devices, their ports and software applications, utilizing the HATEOAS principle. **Note that not all methods must be supported by all of these types of assets.**
    
    ## Legal Disclaimer 
    
    ### © Copyright 2021-2023  Labs Network Industrie 4.0
    
    This work is licenced under the Creative Commons Zero Licence 
    (https://creativecommons.org/publicdomain/zero/1.0/deed.de)
    
    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification.
    THIS SPECIFICATION IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SPECIFICATION OR THE USE OR OTHER DEALINGS IN THE SPECIFICATION.

servers:
  - url: '{scheme}://{gatewayaddress}/{addresspath}'
    description: Generic Edge API 
    variables:
      scheme:
        description: 'The API might be available over https and/or http'
        enum:
          - 'https'
          - 'http'
        default: 'http'  
      baseaddress:
        description: 'The API is accessed via a network address which can contain a network port number'
        enum:
          - 'ip-address'
          - 'dns-name'
        default: 'ip-address'          
      addresspath:
        description: 'The API supports address paths to address substructures to the discrete endpoint. A portId adresses a port instance and an assetId a connected asset in the substructure (i.e. a device). Information about the available substructures is delivered by GET /tree'
        enum:
          - 'assetId'
          - 'portId'
          - 'assetId/portId'
          - 'subs'     #identifies a subsystem or substructure
        default: 'assetId'          
  - url: https://{gatewayaddress}
    description: Adressing a networked asset
  - url: http://{gatewayaddress}/porttId  
    description: Adressing a port instance on an asset
  - url: http://{gatewayaddress}/assetId
    description: Adressing an asset via a networked gateway
  - url: http://{gatewayaddress}/assetId/portId
    description: Adressing a port instance on an asset via a networked gateway
    

tags:
  - name: General
    description: Access to general information
  - name: Edge Asset Management
    description: Manage assets (i.e. devices, applications) in the edge management system directory
  - name: Asset Management
    description: Manage individual assets (i.e. devices, applications) directly    
  - name: Parameter Handling 
    description: (Functional View, ch. 5.4.2) 
  - name: Deployment Functions
    description: (Functional View, ch. 5.4.3) The Deployment of entities (applications) encompasses the initial installation and configuration of the application in question.


paths:
  /:
    get:
      tags:
        - General
      operationId: getRootLinks
      summary: retrieve functional, structural and api information of the root/gateway asset as a list of links according to the HATEOAS principle.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResLinks'
          description: Successful response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
        
  /openapi:
    get:
      tags:
        - General
      operationId: getApi       
      summary: Get the REST interface description of this API as OpenAPI document.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: string
                format: yaml

  '/login':
    get:
      tags:
        - General
      operationId: getLogin
      summary: Returns the login status of the user
      description: >-
        Returns the login status of the user as a boolean value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  isLoggedIn:
                    type: boolean
                  userRole:
                    type: string
                    description: 'Is true in case of a valid user, that is logged in.'
              example:
                isLoggedIn: true
                userRole: 'Operator'                    
    post:
      tags:
        - General
      summary: Logs in with credentials and returns the session bearer token.
      description: >-
         Credentials based authentication - Depending on technical feasibility, the HTTP cookie header shall be used. If the backend does not support cookies, the session bearer token shall be sent in the JSON body. The client has to support both mechanisms.
      operationId: postUsersLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
              example:
                username: fred
                password: '12345678'
      security: []
      responses:
        '200':
          description: >
            Successfully authenticated. <br><br> The set cookie header is only
            sent if the server supports HTTP cookies. Otherwise, the session ID
            is also sent in the JSON body.
          headers:
            Set-Cookie:
              schema:
                type: string
                example: SESSIONID=abcde12345; Path=/; HttpOnly; Secure;
          content:
            application/json:
              schema:
                required:
                  - userRole
                properties:
                  SESSIONID:
                    type: string
                  userRole:
                    type: string
                    enum:
                        - Operator
                        - Maintenance
                        - Specialist
              examples:
                without cookie handling:
                 value:
                  SESSIONID: abc123abc123
                  userRole: Maintenance
                with cookie handling:
                 value:
                  userRole: Maintenance                   

  '/logout':
    post:
      tags:
        - General
      summary: Logs out and invalidates the session token.
      description: >-
        This command does not discern between a logged out or a logged in user.
      operationId: postUsersLogout
      responses:
        '204':
          description: |
            Successfully logged out. Session-Token is now invalid.
        '401':
          description: |
            Session-Token invalid or not found. No action.
          content:
            application/json:
              example:
                code: 141
                message: 'Unknown SESSIONID'
  /assets:
    get:
      summary: retrieve current asset directory content on an edge system
      operationId: listAssets
      tags:
        - Edge Asset Management
      parameters:        
      - name: authorization
        in: header
        description: Access token / Key token
        required: true
        schema:
          type: string
      - name: organisationId
        in: query
        description: The id property defines the unique id of type integer
        required: true
        schema:
          minimum: 1
          type: integer
      - name: deviceType
        in: query
        description: Device types
        schema:
          type: string
          enum:
          - standard
          - sensorEDGE
      - name: page
        in: query
        description: min(1), null and empty values are not allowed
        schema:
          minimum: 1
          type: integer
          default: 1
      - name: limit
        in: query
        description: min(1) / max is set by config pageEntries, null and empty values
          are not allowed
        schema:
          maximum: 5000
          minimum: 1
          type: integer
          default: 10
      - name: sortBy
        in: query
        description: Sort by "name" or other resource property, null not allowed
        schema:
          type: string
          default: id
      - name: sortOrder
        in: query
        description: valid - "asc" and "desc", null and empty string not allowed
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: A paged array of assets. The name of each array element should reflect the base URL.
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Assets"
              example:
                - "https://{gatewayaddress}":
                    DeviceClass: edgeDevice                  
                    Manufacturer: EdgeVendor GmbH
                    ProductCode: EG-123456789
                    Model: Edge Gateway
                    HardwareRevision: 1.2
                    SoftwareRevision: 3.2.1
                    SerialNumber: DE987654321  
                - https://{gatewayaddress}:
                    DeviceClass: gatewayDevice
                    Manufacturer: Murrelektronik
                    Model: MVK PN FDI6/3 FDO2/1 DIO4 IOL2 IRT PP
                    ProductCode: 55510
                    HardwareRevision: 1.0
                    SoftwareRevision: 2.0.1
                    SerialNumber: DE987654321
                    ProductInstanceUri: "https://shop.murrelektronik.com/55510/"
                    applicationSpecificTag: "***"
                    shortDescription: "MVK Fusion with safe inputs/outputs."
                    geolocation:
                    sysUpTime:
                - https://{gatewayaddress}/{assetId}:
                    DeviceClass: fieldDevice
                    Manufacturer: Murrelektronik
                    Model: MVP12 DI16 IOL
                    ProductCode: 59401
                    HardwareRevision: 1.1
                    SoftwareRevision: 1.0.3
                    SerialNumber: DE123456789
                    ProductInstanceUri: "https://shop.murrelektronik.com/59401/"
                    applicationSpecificTag: "***"
                    shortDescription: "MVP12 8xM12 DI16 IOL IO-Link Version 1.12"
                    geolocation:
                    sysUpTime:                    
                - https://{gatewayaddress}/{assetId}:
                    DeviceClass: edgeApp                  
                    Manufacturer: AppVendor Inc
                    Model: Asset Management                    
                    ProductCode: PROD-123456
                    SoftwareRevision: 1.0.0                      
                - https://{gatewayaddress}/{assetId}:
                    DeviceClass: file                  
                    Manufacturer: AppVendor Inc
                    Model: Asset Management                    
                    ProductCode: PROD-123456
                    SoftwareRevision: 1.0.0                    
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: register a notification
      operationId: registerNotification
      tags:
        - Edge Asset Management
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                
  /assets/register:
    post:
      summary: register a asset to a tenant or organisation within the edge management system.     
      description: related to Functional View "5.1.1.2  Edge Device Detection". When an asset is detected, the EMS is informed. This command allows to register the asset. 
      operationId: assetsregister
      tags:
        - Edge Asset Management
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /apps/deploy:
    post:
      summary: deploy an application to an edge device within the edge management system.     
      description: related to Functional View "???".  
      operationId: appregister
      tags:
        - Edge Asset Management
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
################################################################################
  /identification:
    get:
      summary: retrieve identification nameplate of the asset
      operationId: getIdentity
      tags:
        - Asset Management
      responses:
        '200':
          description: returns the identification nameplate of the addressed asset
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/AssetIdentification"
              examples:
                iolMaster:
                  value:
                    URL: https://{basepath}
                    DeviceClass: gatewayDevice
                    Manufacturer: Murrelektronik
                    Model: MVK PN FDI6/3 FDO2/1 DIO4 IOL2 IRT PP
                    ProductCode: 55510
                    HardwareRevision: 1.0
                    SoftwareRevision: 2.0.1
                    SerialNumber: DE987654321
                    ProductInstanceUri: "https://shop.murrelektronik.com/55510/"
                    applicationSpecificTag: "***"
                    shortDescription: "This is the world best IO-Link-Master ;-)"
                    geolocation:
                    sysUpTime:
                iolDevice:
                  value:
                    URL: https://{basepath}/{assetId}                   
                    DeviceClass: fieldDevice
                    Manufacturer: Murrelektronik
                    Model: MVP12 DI16 IOL
                    ProductCode: 59401
                    HardwareRevision: 1.1
                    SoftwareRevision: 1.0.3
                    SerialNumber: DE123456789
                    ProductInstanceUri: "https://shop.murrelektronik.com/59401/"
                    applicationSpecificTag: "***"
                    shortDescription: "MVP12 8xM12 DI16 IOL IO-Link Version 1.12"
                    geolocation:
                    sysUpTime:   
                ioDevice:
                  value:
                    URL: https://{basepath}/{assetId}/{assetId}                  
                    DeviceClass: ioDevice
                    Manufacturer: Murrelektronik
                    Model: MVP12 DI16 IOL
                    ProductCode: 59401
                    HardwareRevision: 1.1
                    SoftwareRevision: 1.0.3
                    SerialNumber: DE123456789
                    ProductInstanceUri: "https://shop.murrelektronik.com/59401/"
                    applicationSpecificTag: "***"
                    shortDescription: "MVP12 8xM12 DI16 IOL IO-Link Version 1.12"
                    geolocation:
                    sysUpTime:                        
                edgeGateway:
                  value:  
                    URL: https://{basepath}                  
                    DeviceClass: edgeDevice                  
                    Manufacturer: EdgeVendor GmbH
                    ProductCode: EG-123456789
                    Model: Edge Gateway
                    HardwareRevision: 1.2
                    SoftwareRevision: 3.2.1
                    SerialNumber: DE987654321                    
                application:
                  value:  
                    URL: https://{basepath}/{assetId}                      
                    DeviceClass: edgeApp                  
                    Manufacturer: AppVendor Inc
                    Model: Asset Management                    
                    ProductCode: PROD-123456
                    SoftwareRevision: 1.0.0                         
                port:
                  value:  
                    DeviceClass: IO                   
                    portId: X0                  
                    
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"    
  /picture:
    get:
      summary: retrieve picture image of the asset
      operationId: getImage
      tags:
        - Asset Management
      responses:
        '200':
          description: returns an image of the addressed asset
          content:
              image/png:
                schema: 
                  type: string
                  format: binary                   
        default:
          description: not supported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
################################################################################   
  /capabilities:
    get:
      summary: retrieve functional, structural and api information of the asset
      operationId: getAPI
      tags:
        - Asset Management
      responses:
        '200':
          description: returns the structural interface specification of the addressed asset, an array of resource URIs
          content:
            application/json:    
              schema:
                type: array # an array of resource URIs and some basic information 
                items:
                  type: object
                  required:
                    - portId
                    - portType
                    - portMode
                    - statusInfo
                  properties:
                    portType:
                      type: string   # TBD: ENUMS for PWR/ETH/IOL/IO
                    porMode:
                      type: string   # TBD: ENUMs for autoNeg, 10000, 100000, 1000000                   
                    statusInfo:
                      type: string
              examples:
                w3cThing:
                  value:
                    '@context': https://www.w3.org/2019/wot/td/v1
                    id: urn:dev:ops:32473-impact67-1234
                    title: IMPACT67 Pro
                    securityDefinitions:
                      basic_sc:
                        scheme: basic
                        in: header
                    security:
                      - basic_sc
                    properties:
                      status:
                        type: string
                        forms:
                          - href: https://murrelektronik.com/status
                    actions:
                      toggle:
                        forms:
                          - href: https://murrelektronik.com/toggle
                    events:
                      overheating:
                        data:
                          type: string
                        forms:
                          - href: https://murrelektronik.com/oh
                            subprotocol: longpoll
               
                ethernetSwitch:
                  value:
                   - endpoints: # list of endpoints that are accessible on the asset:
                     - "{scheme}://{gatewayaddress}/subs/XD1":
                        portType: PWR
                        statusInfo: "OK"
                     - "{scheme}://{gatewayaddress}/subs/XD2":
                        portType: PWR
                        statusInfo: "OK"                  
                     - "{scheme}://{gatewayaddress}/subs/XF1":
                        portType: ETH
                        portMode: autoNeg
                        statusInfo: "CONNECTED"
                     - "{scheme}://{gatewayaddress}/subs/XF2":
                        portType: ETH
                        portMode: "100000"                      
                        statusInfo: "DISCONNECTED"
                     - "{scheme}://{gatewayaddress}/subs/XF3":
                        portType: ETH
                        portMode: autoNeg
                        statusInfo: "CONNECTED"
                     - "{scheme}://{gatewayaddress}/subs/XF4":
                        portType: ETH
                        portMode: "100000"                      
                        statusInfo: "DISCONNECTED"
                   - methods: # list of methods that are accessible on the asset:
                     - factoryReset:
                        type: ALL  #ALL/CFG
                     - configSave: 
                        type: LOCAL # LOCAL/REMOTE
                     - configLoad:
                        type: LOCAL # LOCAL/REMOTE
                     - ledBlink:
                        type: FLASH
                        duration: 5
                                         
                iolMaster:
                  value:
                   - endpoints: # list of endpoints that are accessible on the asset:                  
                     - "{scheme}://{gatewayaddress}/subs/XF1":
                        portType: ETH
                        statusInfo: "CONNECTED"
                     - "{scheme}://{gatewayaddress}/subs/XF2":
                        portType: ETH
                        statusInfo: "DISCONNECTED"
                     - "{scheme}://{gatewayaddress}/subs/XD1":
                        portType: PWR
                        statusInfo: "OK"
                     - "{scheme}://{gatewayaddress}/subs/XD2":
                        portType: PWR
                        statusInfo: "OK"
                     - "{scheme}://{gatewayaddress}/iolink/v1/masters/1/ports/X1":
                        portType: IOL
                        statusInfo: "DEVICE_ONLINE"
                        deviceAlias: "Distance_Sensor"
                     - "{scheme}://{gatewayaddress}/subs/X2":
                        portType: IO                 
                        statusInfo: "DIGITAL_INPUT_C/Q"
                        deviceAlias: "Switching_Sensor"
                     - "{scheme}://{gatewayaddress}/iolink/v1/masters/1/ports/X3":  
                        portType: IOL                 
                        statusInfo: "DEVICE_ONLINE"                  
                        deviceAlias: "Wireless_Bridge"
                        deviceURI: "{scheme}://{gatewayaddress}/iolink/v1/devices/Wireless_Bridge"
                        deviceInfo:
                          vendorId: 888
                          deviceId: 10485760
                          productName: "BNI IOW-302-W01-K080" 
                     - "{scheme}://{gatewayaddress}/subs/X4":
                        portType: IOL                 
                        statusInfo: "DEACTIVATED"     
                   - methods: # list of methods that are accessible on the asset:
                     - factoryReset:
                        type: ALL  #ALL/CFG
                     - configSave: 
                        type: LOCAL # LOCAL/REMOTE
                     - configLoad:
                        type: LOCAL # LOCAL/REMOTE
                     - ledBlink:
                        type: FLASH
                        duration: 5                      
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"  
################################################################################
  /device:
    description: Retrieve the hardware structure and access methods of a device asset (i.e. ports, LEDs).
    get:
      tags:
        - Asset Management
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/ResLinks'
              examples:
                EthernetSwitch:
                  value:
                    links:
                      - href: /device/XD1
                        rel: Power
                        type: GET
                      - href: /device/XD2
                        rel: Power
                        type: GET
                      - href: /device/XF1
                        rel: ETH
                        type: GET
                      - href: /device/XF2
                        rel: ETH
                        type: GET
                      - href: /device/XF3
                        rel: ETH
                        type: GET
                      - href: /device/XF4
                        rel: ETH
                        type: GET
                IOLinkMaster:
                  value:
                    links:
                      - href: /iolink/v1/masters/1/ports/1"
                        rel: IOL
                        type: GET
                      - href: /iolink/v1/masters/1/ports/2"
                        rel: IOL
                        type: GET
                      - href: /iolink/v1/masters/1/ports/3"
                        rel: IOL
                        type: GET
                      - href: /iolink/v1/masters/1/ports/3"
                        rel: IOL
                        type: GET
          description: returns the structural hardware interface specification of the addressed root             device asset, an array of resource URIs. Previously implemented /external resource may not follow our API design principles.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unexpected error
      operationId: getRootDeviceStructure
      summary: retrieve functional, structural and api information of the root device asset
      description: Get device HW and SW components.
################################################################################       
  /diagnostics:
    get:
      summary: retrieve diagnostic informations of the asset
      operationId: getDiagnostics
      tags:
        - Asset Management      
      parameters:
        - $ref: '#/components/parameters/topic' 
      responses:
        '200':
          description: returns the diagnostics information of the addressed asset as array of functional status groups
          content:
            application/json:    
              schema:
                type: array 
                minItems: 1
                items:
                  type: object
              example:
               - "Health":
                  healthState: 78               
               - "RSTP":
                  RstpBridgeStatus: "true"
                  is_root_bridge: "true"
                  time_since_topology_change: "100"
                  topology_change_count: "100"

               - "PortStatistics":
                  - "XF1":
                      octets_in: 0
                      octets_out: 0
                      undersized_packets: 0
                      oversized_packets: 0
                      fragments: 0
                      crc_errors: 0
                      jabbers: 0
                      collisions: 0
                  - "XF2":
                      octets_in: 0
                      octets_out: 0
                      undersized_packets: 0
                      oversized_packets: 0
                      fragments: 0
                      crc_errors: 0
                      jabbers: 0
                      collisions: 0                        
               
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"                    
################################################################################  
  /configuration:
    get:
      summary: retrieve configuration variables of the asset
      operationId: getConfigutration
      tags:
        - Asset Management
      parameters:
        - $ref: '#/components/parameters/topic'         
      responses:
        '200':
          description: returns the configuration items of the addressed asset
          content:
            application/json:    
              schema:
                type: array # an array of functional configuration groups
                items:
                  type: object
              example:
                   - "snmp":
                     v1_v2_ro_community: bla
                     v1_v2_rw_community: blub
                     use_v1: true
                     use_v2: true
                     use_v3: false
                     
                   - "mac_filter": # Die MAC-Adressen für die eine Filterregel gesetzt werden soll
                      - mac: 00:11:22:33:44
                        unaware_mode: true
                      - vlan_id: 1 # Die ID des VLANs für das die MAC-Filterregel gelten soll
                        portList: 
                          XF1: true
                          XF2: false                          
                      - vlan_id: 2
                        name: "vlan_1"
                        portList:
                          XF2: true
                          XF3: true                    
                   - "VLAN":
                      - management_vlan: 1
                        unaware_mode: true
                        max_vlans: 10
                        # Portmodus: "-" for NoMember, "N" for Unchanged, "U" for Untagged, "T" for Tagged
                      - "1": # Die ID des VLANs
                          name: "vlan_1"
                          portList:
                            XF1: 
                             mode: "-"
                             ingress_filter: false
                            XF2: 
                             mode: "U"
                             ingress_filter: true                           
                      - "2": # Die ID des VLANs
                          name: "vlan_2"
                          portList:
                            XF2: "T"
                            XF3: "U"      
                          
                   - "Network":
                      ipConfiguration: MANUAL
                      ipAddress: 192.168.1.13
                      subnetMask: 255.255.255.0
                      standardGateway: 192.168.1.1
                      sysName: "myEthernetSwitch"
                      sysContact: "justMe"                    
                      applicationSpecificTag: "forSwitching"
                 
                   - "RSTP":
                      designated_root_pri: "100"
                      designated_root_mac: "100"
                      root_port: "100"
                      root_path_cost: "100"
                      bridge_priority: "100"
                      bridge_mac: "100"
                      bridge_max_age: "100"
                      bridge_hello_time: "100"
                      bridge_forward_delay: "100"
                      max_age: "100"
                      hello_time: "100"
                      forward_delay: "100"
                      
                   - "MRP":
                      port1: 123
                      port2: 456  

        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"               
    post:
      summary: update a set of configuration variables of the asset
      operationId: changeConfiguration
      tags:
        - Asset Management
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"                
             
components:
  schemas:
    AssetIdentification:
      type: object
      required:
        - DeviceClass
        - Manufacturer
        - ManufacturerUri                  
        - Model                  
        - ProductCode                    
        - productInstanceUri
        - onBoardedAt
      properties:
        DeviceClass:          # identifies the asset type
          type: string
          enum:
           - edgeApp
           - edgeDevice
           - fieldDevice
        Manufacturer:         # vendorName
          type: string
        ManufacturerUri:      # vendorUrl
          type: string                    
        Model:                # productName
          type: string                    
        ProductCode:          # productId
          type: string
        HardwareRevision:     # hardwareRevision
          type: string
        SoftwareRevision:     # softwareRevision
          type: string
        SerialNumber:         # serialNumber
          type: string   
        ProductInstanceUri:   # AssetId
          type: string  
        ManualUrl:            # Link to manual
          type: string                     
        sysName:              # DNS HostName, SNMP: sysName, PROFINET: nameOfStation, IO-Link: deviceAlias
          type: string                    
        sysLocation:          # description of the hosts's location (i.e. an address).
          type: string  
        sysContact:           # contact data of the responsible person or organization (i.e. an email address).
          type: string 
        onBoardedAt:          # date/time when the asset has first appeared.
          type: string
          description: onBoardedAt
          format: date-time          
        geolocation:          # physical location of the assset.
          required:
          - latitude
          - longitude
          type: object
          properties:
            longitude:
              type: string
            latitude:
              type: string
    ResLink:
      type: object
      properties:
        href:
          description: Link to available resources eg. "/capabilities". Must be relative path to baseUri
          type: string
        rel:
          description: Relationship to the linked resource
          type: string
        type:
          description: Supported http method ("get", "post", "delete", "put", "patch")
          type: string    
          required:
          - href
          - rel
          - type
          
    ResLinks:
      type: object
      description: List of links to available resources according to HATEOAS principle      
      properties:
        baseURI:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/ResLink'
      example:
        baseURI: "{scheme}://{gatewayaddress}/{addresspath}"
        links:
            - href: /identification
              rel: identification
              type: GET
            - href: /picture
              rel: picture
              type: GET
            - href: /openapi
              rel: api
              type: GET
            - href: /users
              rel: usermanagement
              type: GET
            - href: /logout
              rel: security
              type: POST
            - href: /configuration
              rel: configuration
              type: GET
            - href: /diagnostics
              rel: diagnostics
              type: GET
            - href: /device
              rel: device
              type: GET
            
    Assets:
      type: array
      items:
        $ref: "#/components/schemas/AssetIdentification"
   
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  parameters:
    topic:
      name: topic
      in: query
      description: ID of a topic to filter (empty=retrive all).
      required: false
      schema:
        type: string