openapi: 3.0.0
info:
  x-audience: external-partner
  x-api-id: 4fefe95d-8907-42b6-bd16-942aa1916b58
  title: Assets API
  description: |
    This API allows administering assets, devices, and associations between assets and devices in the RIO platform.

    ## Taxonomy

    * An `asset` is an abstract representation of a physical item that takes part in fulfilling logistic or transport
    tasks. Examples are trucks, vans, trailers, or a handling units. Each asset belongs to an account. Any physical item
    can have multiple such representations as an asset, e.g. if a truck is being rented, there is both an asset
    representing the truck in the rental company's account as well as another representation of the truck in the
    renter's account. One asset can have multiple devices associated with it.

    * A (telematic) `device` is a hardware or software component that has the ability to send data to the RIO platform.
    Devices are data sources for IoT sensor events, e.g. position data. Only dedicated connectors are allowed to
    administer devices and devices are not account specific. One device can be associated with multiple assets.

    * An `association` is the connection of a single device with a single asset. Any device can be associated with
    multiple assets, and one asset can be associated with multiple devices. Any data sent by a device is allocated to
    each associated asset.

    ## Typical usecases

    * Create/update/delete an asset to administrate this asset in a account.

    * Retrieve a list of all assets in a user account.

    * Create a device and associate it to an asset to send telematics data to the owner of that asset.

    * Associate multiple assets with a single device to model rental or subcontracting use cases.

    * Associate multiple devices with a single asset to gather data from several data sources.

  version: 1.1.2
  contact:
    name: Team Network
    email: rio_team_network@rio.cloud
    url: https://rio.cloud
tags:
  - name: Asset Events
    description: Receive new create, update, delete events of assets
  - name: Assets
    description: Asset administration
  - name: Asset Tags
    description: Asset tag administration
  - name: Asset Master Data
    description: Assets master data (additional data)
  - name: Devices
    description: Device administration
  - name: Associations
    description: Device to asset association administration
  - name: Vehicle Identification Number
    description: Details determined from a VIN
paths:
  '/asset-events':
    get:
      tags:
        - Asset Events
      summary: Returns a list of asset events
      description: |
        Returns all asset events or only asset events that occurred after a specified offset.

        ## Example queries

          * Get all asset events for a RIO account. (Typically used when events for an asset are queried for the first time.)
            `GET /asset-events`

          * Get all asset events after the specified offset:
            `GET /asset-events?after=003JZ9J6G80123456789ABCDEF`
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AssetEventList'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
  '/assets':
    get:
      tags:
        - Assets
      summary: Retrieve a list of assets
      description: |
        Rerieve all assets matching the query parameters.

        ### Example use case

        * Retrieve all assets:
          `GET /assets`

        * Retrieve all archived assets:
          `GET /assets?status=archived`

        * Retrieve all active trucks:
          `GET /assets?status=active&type=truck`

        * Retrieve all assets with a specific VIN WMA11111111111111:
          `GET /assets?identification=WMA11111111111111&identification_type=vin`

        * Retrieve all active assets with the specific VIN WMA11111111111111:
          `GET /assets?identification=WMA11111111111111&identification_type=vin&status=active`

        * Retrieve all active assets with license plate JA-M-222:
          `GET /assets?license_plate=JA-M-222&status=active`

        * Retrieve all assets including their tags:
          `GET /assets?embed=(tags)`
        
        * Retrieve all assets including additional masterdata:
          `GET /assets?embed=(master_data)`

        * Retrieve all active assets including their tags:
          `GET /assets?status=active&embed=(tags)`

        * Retrieve all trailers including their tags and master data:
          `GET /assets?type=trailer&embed=(tags,master_data)`

        * Retrieve a slice of assets after a certain offset with limit:
          `GET /assets?after=8ff941da-858d-11eb-a7fa-784f43566792&limit=100`

      operationId: getAssets
      parameters:
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/asset_identification'
        - $ref: '#/components/parameters/asset_identification_type'
        - $ref: '#/components/parameters/asset_type'
        - $ref: '#/components/parameters/license_plate'
        - $ref: '#/components/parameters/assets_embed'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AssetEmbeddedList'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
  '/assets/{asset-id}':
    parameters:
      - $ref: '#/components/parameters/asset-id'
    get:
      tags:
        - Assets
      summary: Retrieve an asset
      description: |
        Retrieve the asset with the id specified in the path.
      operationId: getAsset
      parameters:
        - $ref: '#/components/parameters/assets_embed'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Asset'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
    put:
      tags:
        - Assets
      summary: Create or update an asset
      description: |
        Create or update the asset with the id specified in the path.
        The id in the path must match the id provided in the content body.
      operationId: putAsset
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Asset'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/AssetLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
    delete:
      tags:
        - Assets
      summary: Delete an asset
      description: |
        Delete the asset with the id specified in the path.
      operationId: deleteAsset
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/AssetLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
  '/assets/{asset-id}/tags':
    parameters:
      - $ref: '#/components/parameters/asset-id'
    get:
      tags:
        - Asset Tags
      summary: Retrieve the tags of an asset
      description: |
        Retrieve the tags of the asset.
      operationId: getAssetTags
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TagList'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
  '/assets/{asset-id}/tags/{tag-id}':
    parameters:
      - $ref: '#/components/parameters/asset-id'
      - $ref: '#/components/parameters/tag-id'
    get:
      tags:
        - Asset Tags
      summary: Retrieve a tag of an asset
      description: |
        Retrieve the tag of an asset.
      operationId: getAssetTag
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Tag'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
    put:
      tags:
        - Asset Tags
      summary: Tag an asset
      description: |
        Add the tag with the id specified in the path to the asset with the id specified in the path.
        The id in the path must match the id provided in the content body.
      operationId: tagAsset
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/TagLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
    delete:
      tags:
        - Asset Tags
      summary: Untag an asset
      description: |
        Remove the tag with the id specified in the path from the asset with the id specified in the path.
      operationId: untagAsset
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/TagLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
  '/assets/{asset-id}/masterdata':
    parameters:
      - $ref: '#/components/parameters/asset-id'
    get:
      tags:
        - Asset Master Data
      summary: Retrieve the master data for an asset
      description: |
        Retrieve the master data for the id specified in the path.
      operationId: getMasterData
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AssetMasterData'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
    patch:
      tags:
        - Asset Master Data
      summary: update a master data
      description: |
        Update the master data for an asset with the id specified in the path.
      operationId: patchMasterData
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/AssetMasterData'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/MasterDataLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
  '/devices':
    get:
      tags:
        - Devices
      summary: Retrieve a list of devices
      description: |
        Rerieve all devices matching the query parameters.

        ## Example use case

        * Retrieve all TBM3 devices:
          `GET /devices?device_type=tbm3`
        * Retrieve all TBM3 devices with the serial number `181113-0083`:
          `GET /devices?device_type=tbm3&identification=181113-0083`
        * Retrieve all TBM3 devices which have not been associated with any asset for some time:
          `GET /devices?device_type=tbm3&orphaned=true`
        * Retrieve a slice of TBM3 devices after a certain offset with limit:
                  `GET /devices?device_type=tbm3&after=8ff941da-858d-11eb-a7fa-784f43566792&limit=100`
      operationId: getDevices
      parameters:
        - $ref: '#/components/parameters/device_type'
        - $ref: '#/components/parameters/device_identification'
        - $ref: '#/components/parameters/device_orphaned'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DeviceList'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
  '/devices/{device-id}':
    get:
      tags:
        - Devices
      summary: Retrieve a device
      description: |
        Retrieve the device with the id specified in the path.
      operationId: getDevice
      parameters:
        - $ref: '#/components/parameters/device-id'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
    put:
      tags:
        - Devices
      summary: Create or update device
      description: |
        Create or update the device with the id specified in the path.
        The id in the path must match the id provided in the content body.
      operationId: putDevice
      parameters:
        - $ref: '#/components/parameters/device-id'
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Device'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/DeviceLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
    delete:
      tags:
        - Devices
      summary: Delete a device
      description: |
        Delete the device with the id specified in the path.
      operationId: deleteDevice
      parameters:
        - $ref: '#/components/parameters/device-id'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/DeviceLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
  '/associations':
    get:
      tags:
        - Associations
      summary: Retrieve a list of associations e.g. for a particular asset
      description: |
        Rerieve all associations matching the query parameters.

        ## Example use case

        * Retrieve all associations for the device with the id `5aa0f223-8f11-4a73-b7ea-14e7b1e0971c` including all data
          of the associated assets:
          `GET /associations?device_id=5aa0f223-8f11-4a73-b7ea-14e7b1e0971c&embed=(asset)`

        * Retrieve all associations for the the asset with the id `dda9e676-3ec9-494f-910e-a9ebff23ae50` including all data
          of the associated devices:
          `GET /associations?asset_id=dda9e676-3ec9-494f-910e-a9ebff23ae50&embed=(device)`

        * Retrieve all associations without any data of the associated devices and assets:
          `GET /associations`

        * Retrieve all associations including all data of the associated devices and assets:
          `GET /associations?embed=(device,asset)`

        * Retrieve a slice of associations after an offset with a set limit:
          `GET /associations?after==8ff941da-858d-11eb-a7fa-784f43566792&limit=100`
      operationId: getAssociations
      parameters:
        - $ref: '#/components/parameters/device_id'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/associations_embed'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AssociationEmbeddedList'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
  '/associations/{association-id}':
    get:
      tags:
        - Associations
      summary: Retrieve an association
      description: |
        Retrieve the association with the id specified in the path.
      operationId: getAssociation
      parameters:
        - $ref: '#/components/parameters/association-id'
        - $ref: '#/components/parameters/associations_embed'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AssociationEmbedded'
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
    put:
      tags:
        - Associations
      summary: Create or update an association
      description: |
        Create or update the association with the id specified in the path.
        The id in the path must match the id provided in the content body.
      operationId: createAssociation
      parameters:
        - $ref: '#/components/parameters/association-id'
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Association'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/AssociationLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
    delete:
      tags:
        - Associations
      summary: Delete an association
      description: |
        Delete the association with the id specified in the path.
      operationId: deleteAssociation
      parameters:
        - $ref: '#/components/parameters/association-id'
      responses:
        '202':
          description: Accepted
          headers:
            'Location':
              schema:
                $ref: '#/components/schemas/AssociationLocation'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.write
  '/vins/{vin}':
    get:
      tags:
        - Vehicle Identification Number
      summary: Retrieve the details of a VIN, e.g. the encoded brand
      description: |
        Resolve details of the vehicle encoded in the VIN, e.g. the brand of the vehicle.
      operationId: getVinDetails
      parameters:
        - $ref: '#/components/parameters/vin'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/VinDetails'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      security:
        - oauth2:
            - asset-administration.read
x-zally-ignore:
  - 224 # Must: Follow Naming Convention for Hostnames
servers:
  - url: 'https://api.assets.rio.cloud'
components:
  schemas:
    AssetCreatedOrUpdatedEvent:
      type: object
      required: [ id, account_id, name, type, status ]
      properties:
        id:
          description: |
            UUIDv4. Unique identifier of the asset.
          type: string
          format: uuid
          nullable: false
          example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
        account_id:
          description: |
            Unique identifier of the account the asset belongs to. Usually a UUID, but can also be a non-UUID and therefore needs to be treated as a string.
          type: string
          nullable: false
          example: '992b907d-a2cd-40c7-8f76-13a2f3d465c8'
        name:
          description: |
            Account specific name of an asset. Mandatory for creation and therefore must contain at least one valid character. Can change over time.
          type: string
          nullable: false
          minLength: 1
          maxLength: 255
          example: My Truck
        identification:
          description: |
            Identification of the asset, e.g. VIN. Can only be specified once in combination with a valid identification type.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: WP0ZZZ99ZTS392124
        identification_type:
          $ref: '#/components/schemas/IdentificationType'
        type:
          $ref: '#/components/schemas/AssetType'
        status:
          $ref: '#/components/schemas/AssetStatus'
        brand:
          description: |
            Brand of the asset. Can change over time.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: MAN
        license_plate:
          description: |
            License plate of the asset. Can change over time.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: JA-M-222
        license_plate_country_code:
          description: |
            ISO 3166 alpha-2 country code for the country in which the asset is registered.
            Only mandatory when license plate provided. Can change over time.
          type: string
          format: '^[A-Z]{2}$'
          nullable: true
          minLength: 2
          maxLength: 2
          example: DE
        master_data:
          $ref: '#/components/schemas/AssetMasterData'
        associated_devices:
          type: array
          nullable: false
          description: Associated devices
          items:
            $ref: '#/components/schemas/Device'
        tags:
          type: array
          nullable: false
          description: Tags of the assets
          items:
            $ref: '#/components/schemas/Tag'
    AssetDeletedEvent:
      type: object
      required: [ id ]
      properties:
        id:
          description: |
            UUIDv4. Unique identifier of the asset.
          type: string
          format: uuid
          nullable: false
          example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
    AssetEvent:
      description: Event that wraps an asset created, updated or deleted event.
      type: object
      properties:
        id:
          description: |
            The id of the this event. Consecutive events may not have consecutive ids.
            Universally Unique Lexicographically Sortable Identifier (https://github.com/ulid/spec)
          type: string
          format: ulid
          example: '01F7BFC0E9G0GM0RY1ZRHX02WK'
        type:
          description: Name of the event that triggered the delivery. All lowercase and always starts with a "/" character.
          type: string
          x-extensible-enum:
            - '/asset/createdOrUpdated'
            - '/asset/deleted'
          example: '/asset/createdOrUpdated'
        timestamp:
          description: Timestamp when the event was fired. Format according to ISO 8601 ("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").
          type: string
          format: date-time
          example: 2015-08-29T11:22:09.000Z
        payload:
          description: The event Payload
          oneOf:
            - $ref: '#/components/schemas/AssetCreatedOrUpdatedEvent'
            - $ref: '#/components/schemas/AssetDeletedEvent'
          example: { }
      required:
        - id
        - type
        - timestamp
        - payload
    AssetEventList:
      type: object
      required: [ items, _links ]
      properties:
        items:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/AssetEvent'
        _links:
          $ref: '#/components/schemas/AssetEventsPaginationLinks'
    Id:
      description: |
        UUIDv4
      type: string
      format: uuid
      nullable: false
      example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
    IdString:
      description: |
        Plain string
      type: string
      nullable: false
      minLength: 1
      maxLength: 255
      example: '72185d23-b7a8-4508-b0cc-a40356aa724c'
    AssetStatus:
      description: |
        Status of the asset. Mandatory, changeable.

        If the asset is `active`, the asset is currently in use and the data sent by any associated device gets processed.

        If the asset is `archived`, the asset is not in use anymore (maybe it was rented formerly or has been sold).
        All associate devices are removed from the asset at the time of archiving so that no more data gets processed.
      type: string
      x-extensible-enum:
        - active
        - archived
      nullable: false
      example: active
    AssetType:
      description: |
        Type of the asset. Mandatory, not changeable.
      type: string
      x-extensible-enum:
        - bus
        - car
        - trailer
        - truck
        - van
      nullable: false
      example: truck
    IdentificationType:
      description: |
        The identification type of the asset. Can only be specified once together with a valid identification.
      type: string
      x-extensible-enum:
        - vin
      nullable: true
      example: vin
    Asset:
      type: object
      required: [id, account_id, name, type, status]
      properties:
        id:
          description: |
            UUIDv4. Unique identifier of the asset. Mandatory, not changeable.
          type: string
          format: uuid
          nullable: false
          example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
        account_id:
          description: |
            Unique identifier of the account the asset belongs to. Usually a UUID, but can also be a non-UUID and therefore needs to be treated as a string. Mandatory, not changeable.
          type: string
          nullable: false
          example: '992b907d-a2cd-40c7-8f76-13a2f3d465c8'
        name:
          description: |
            Account specific name of an asset.
            Mandatory for creation, must contain at least one valid character. Changeable.
          type: string
          nullable: false
          minLength: 1
          maxLength: 255
          example: My Truck
        identification:
          description: |
            Identification of the asset, e.g. VIN. Can only be specified once together with a valid identification type.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: WP0ZZZ99ZTS392124
        identification_type:
          $ref: '#/components/schemas/IdentificationType'
        type:
          $ref: '#/components/schemas/AssetType'
        status:
          $ref: '#/components/schemas/AssetStatus'
        brand:
          description: |
            Brand of the asset. Mandatory, changeable.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: MAN
        license_plate:
          description: |
            License plate of the asset. Unique per account, not mandatory, changeable.
          type: string
          nullable: true
          minLength: 1
          maxLength: 255
          example: JA-M-222
        license_plate_country_code:
          description: |
            ISO 3166 alpha-2 country code for the assets country of registration.
            Not mandatory, changeable.
          type: string
          format: '^[A-Z]{2}$'
          nullable: true
          minLength: 2
          maxLength: 2
          example: DE
    AssetEmbedded:
      allOf:
        - $ref: '#/components/schemas/Asset'
        - type: object
          properties:
            _embedded:
              description: |
                Embed the tags belonging to an asset using query parameter embed.
              type: object
              nullable: false
              properties:
                tags:
                  $ref: '#/components/schemas/TagList'
                master_data:
                  $ref: '#/components/schemas/AssetMasterData'
    AssetEmbeddedList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/AssetEmbedded'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    TagList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      required: [id]
      properties:
        id:
          description: |
            Unique identifier of a tag of the asset.
          type: string
          nullable: false
          minLength: 1
          maxLength: 255
          example: '992b907d-a2cd-40c7-8f76-13a2f3d465c8'
    DeviceType:
      description: |
        Type of the device. Mandatory, not changeable.
      type: string
      x-extensible-enum:
        - fleet-tech
        - idem-telematics
        - man-webfleet
        - ocu3
        - rfms # deprecated
        - scania-telematics
        - tbm2
        - tbm3
        - timocom
        - tour-execution-user-device
        - traffilog # deprecated
        - truck-login-device # deprecated
        - vcm
        - volvo-telematics
        - wabco-telematics
        - asset
        - cargobull
        - transics
        - fleetboard
        - dako
        - webfleet
        - pocket-driver-app
        - webfleet-retrofit
        - cm4
        - krone
        - koegel-telematics
        - schwarzmueller-telematics
        - renault
        - co3
        - daf
        - vwtb-autotrac
        - vwtb-sascar
        - vwtb-geotab
        - vwtb-infleet
        - vwtb-omnilink
        - vwtb-truckerassist
        - vwtb-vw
        - vwtb-ituran
        - vwtb-vwconnect
      nullable: false
      example: tbm3
    Device:
      type: object
      required: [id, identification, type]
      nullable: false
      properties:
        id:
          description: |
            UUIDv4. Unique identifier of the device. Mandatory, not changeable.
          type: string
          format: uuid
          nullable: false
          example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
        type:
          $ref: '#/components/schemas/DeviceType'
        identification:
          description: |
            Identification of the device, e.g. RIO box serial number.
          type: string
          nullable: false
          minLength: 1
          maxLength: 255
          example: '181113-0083'
    DeviceList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/Device'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    AssetEventsPaginationLinks:
      type: object
      required: [ self, next ]
      description: |
        All links are (absolute) URLs.
        * The `self` link shows the current page.
        * The `next` link is always present and will return further asset events if there are unfetched events left,
        or will return an empty list of items if there are no more asset events at this time.
        Use the `next` link for future requests to retrieve only new events.
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    PaginationLinks:
      type: object
      required: [ self ]
      description: |
        All links are (absolute) URLs.
        * The `self` link shows the current page.
        * The `next` link is only present if the result was paginated and there are still unfetched pages left.
          Follow the `next` link to get the next pages until the `next` link is not present anymore.
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      required: [ href ]
      properties:
        href:
          type: string
          example: 'https://...'
    Association:
      type: object
      required: [id, device_id, asset_id]
      properties:
        id:
          description: |
            UUIDv4. Unique identifier of the association. Mandatory, not changeble.
          type: string
          format: uuid
          nullable: false
          example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
        device_id:
          description: |
            UUIDv4. Unique identifier of the device belonging to this association. Mandatory, not changeble.
          type: string
          format: uuid
          nullable: false
          example: '992b907d-a2cd-40c7-8f76-13a2f3d465c8'
        asset_id:
          description: |
            UUIDv4. Unique identifier of the asset belonging to this association. Mandatory, not changeble.
          type: string
          format: uuid
          nullable: false
          example: '1ae66cbb-a87e-4815-b2df-9c919a32d620'
    AssociationEmbedded:
      allOf:
        - $ref: '#/components/schemas/Association'
        - type: object
          properties:
            _embedded:
              description: |
                Embed the device and/or asset belonging to an association using query parameter embed.
              type: object
              properties:
                device:
                  $ref: '#/components/schemas/Device'
                asset:
                  $ref: '#/components/schemas/Asset'
    AssociationEmbeddedList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          nullable: false
          items:
            $ref: '#/components/schemas/AssociationEmbedded'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    AssetLocation:
      type: string
      example: 'https://api.assets.rio.cloud/assets/67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
    DeviceLocation:
      type: string
      example: 'https://api.assets.rio.cloud/devices/67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
    AssociationLocation:
      type: string
      example: 'https://api.assets.rio.cloud/associations/67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
    TagLocation:
      type: string
      example: 'https://api.assets.rio.cloud/assets/67f5a0c2-6f14-4bb5-9278-b0af7dd45044/tags/72185d23-b7a8-4508-b0cc-a40356aa724c'
    AssetMasterData:
      type: object
      nullable: false
      properties:
        plug_and_charge_ids:
          description: |
            Plug-and-charge ids that are used to create a contract with an electricity provider for electrical vehicles.
          nullable: true
          type: array
          maxLength: 2
          items:
            $ref: '#/components/schemas/PlugAndChargeId'
        cost_center:
          description: >
            Cost center used for accounting.
          example: "0123456789"
          type: string
        customs_bond:
          description: Transport across national borders, seal from customs
          type: string
        adr:
          description: Classification according to Agreement concerning the International Carriage of Dangerous Goods
          example: "1.4S"
          type: string
        air_freight_suitability:
          description: Information on suitability for air freight
          example: "Truck is suitable for air freight"
          type: string
        fuel_type:
          description:  |
            Fuel type of the vehicle.
              - `diesel`: Diesel
              - `hydrogen`: Hydrogen
              - `electric`: Battery/electric
              - `gas`: Gasoline/petrol
              - `cng`: Compressed Natural Gas
            
            Note: Wherever suitable we aim to follow the fuel types as specified in the [FMS-Standard Vers. 05 (p.34)](https://www.fms-standard.com/Truck/down_load/fms%20document_v_05_vers.07.07.2024.pdf#page=34).
          example: diesel
          type: string
          x-extensible-enum:
            - diesel
            - gas
            - electric
            - hydrogen
            - cng
        tires:
          description: Free form information on the tires of the vehicle
          example: "All season tires"
          type: string
        number_of_axes:
          description: >
            Information on number of axes of the vehicle.
          example: 2
          type: integer
        vehicle_model:
          description: Vehicle model
          example: "Volkswagen Type 2 (T1)"
          type: string
        engine_type:
          description: Engine Type of the vehicle
          example: "1.1 L B4"
          type: string
        comment:
          description: Free form comment
          example: "This is the chef's private truck. Be careful."
          type: string
        ownership:
          type: object
          properties:
            registered_first_at:
              type: string
              description: "Date of first registration"
              format: date
            ownership_start_at:
              type: string
              description: "Start of contract"
              format: date
            ownership_end_at:
              type: string
              description: "End of contract"
              format: date
            type:
              type: string
              x-extensible-enum:
                - leasing
                - rental
                - financing
                - ownership
            reference:
              type: string
              description: "Contract reference"
            contract_duration_in_months:
              type: integer
              description: "Contract duration"
            contract_rate:
              type: number
              description: "Contract rate"
    PlugAndChargeId:
      type: object
      nullable: false
      required:
        - pc_id
      properties:
        pc_id:
          type: string
          nullable: false
          minLength: 1
          maxLength: 255
          description: >
            The Plug And Charge Id value aka. Provisioning Certificate Identifier (PCID) as described in VDE-AR-E 2802-100-1:2019-12 and ISO 15118.
            (see: https://support.hubject.com/hc/en-us/articles/8953060243101-4-3-PCID-Provisioning-Certificate-Identifier-)
          example: 'PCIDMSTR0123456789'
    MasterDataLocation:
      type: string
      example: 'https://api.assets.rio.cloud/assets/67f5a0c2-6f14-4bb5-9278-b0af7dd45044/masterdata/d1b27658-545d-4aa0-9ef9-78d2ea98e0e2'
    Vin:
      description: |
        The vehicle identification number (VIN), see https://en.wikipedia.org/wiki/Vehicle_identification_number.
      type: string
      nullable: false
      minLength: 17
      maxLength: 17
      example: 'WMAHW26G0TEA42337'
    VinDetails:
      type: object
      required: [vin, brand]
      properties:
        vin:
          $ref: '#/components/schemas/Vin'
        brand:
          description: |
            Brand determined from the VIN
          type: string
          nullable: false
          example: MAN
  parameters:
    asset-id:
      name: asset-id
      in: path
      required: true
      description: Asset Id
      schema:
        $ref: '#/components/schemas/Id'
    status:
      name: status
      in: query
      description: Asset status
      schema:
        $ref: '#/components/schemas/AssetStatus'
    account_id:
      name: account_id
      in: query
      description: Account id to which assets / associations belongs
      schema:
        $ref: '#/components/schemas/Id'
    asset_identification:
      name: identification
      description: Identification of an asset, e.g. the value of the VIN.
      in: query
      schema:
        type: string
    asset_identification_type:
      name: identification_type
      in: query
      description: Asset identification type, e.g. VIN.
      schema:
        $ref: '#/components/schemas/IdentificationType'
    asset_type:
      name: type
      in: query
      description: Asset type
      schema:
        $ref: '#/components/schemas/AssetType'
    license_plate:
      name: license_plate
      in: query
      description: License plate of the Asset
      schema:
        type: string
    device_type:
      name: device_type
      description: Device type
      in: query
      schema:
        $ref: '#/components/schemas/DeviceType'
    device_identification:
      name: identification
      description: Identification of a device, e.g. RIO box serial number.
      in: query
      schema:
        type: string
    device_orphaned:
      name: orphaned
      description: The device has not been associated with any asset for some time.
      in: query
      schema:
        type: boolean
        example: true
    device-id:
      name: device-id
      in: path
      description: Device Id
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    association-id:
      name: association-id
      in: path
      description: Association id
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    tag-id:
      name: tag-id
      in: path
      required: true
      description: Tag Id
      schema:
        $ref: '#/components/schemas/IdString'
    asset_id:
      name: asset_id
      in: query
      description: Asset id
      schema:
        $ref: '#/components/schemas/Id'
    device_id:
      name: device_id
      in: query
      description: Device id
      schema:
        $ref: '#/components/schemas/Id'
    associations_embed:
      name: embed
      in: query
      description: embed
      schema:
        type: string
      examples:
        'device':
          value: '(device)'
        'asset':
          value: '(asset)'
        'device and asset':
          value: '(device,asset)'
    assets_embed:
      name: embed
      in: query
      description: embed
      schema:
        type: string
      examples:
        'master_data':
          value: '(master_data)'
        'tags':
          value: '(tags)'
        'master_data and tags':
          value: '(tags,master_data)'
    vin:
      name: vin
      in: path
      description: VIN
      required: true
      schema:
        $ref: '#/components/schemas/Vin'
    limit:
      in: query
      name: limit
      description: Limit the number of returned resources in list
      example: 30
      schema:
        type: integer
    after:
      in: query
      name: after
      description: offset for pagination
      example: 84f92a7c-6d81-406d-a636-d7be425fb4df
      schema:
        type: string
  responses:
    DefaultProblemResponse:
      description: >-
        error occurred - see status code and problem object for more information
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://auth.iam.rio.cloud/oauth/token'
          scopes:
            asset-administration.read: Read access to asset administration
            asset-administration.write: Write access to asset administration
