openapi: 3.0.0
x-zally-ignore: [224]
info:
  x-audience: external-partner
  x-api-id: '4ebd0b1b-5b4d-4c80-8e36-6c357e1a51d2'
  title: Maintenance API
  description: |
    The maintenance API provides all maintenance and status data for your fleet.
    What's in it for you? A clear picture of the state of health of all your vehicles and the basis for proactive maintenance planning.
    This gives you the freedom to focus on your core business and organise your fleet more efficiently.

    ## Taxonomy

    ### Components:
    - [Maintenance Components](#/components/schema/MaintenanceComponent)
      - Part of an asset, which is *predefined* and will be due for maintenance at a future date and/or mileage
      - Maintenance components are read-only as the due information is updated automatically by the vehicle computer

    - [Custom components](#/components/schema/CustomComponent)
      - Part of an asset, which is *defined by the user* and will be due for maintenance at a future date and/or mileage
      - Custom components are read-write as the due date / mileage must be specified by the user
      - They can be used to keep track of required maintenance work not accounted for by the vehicle computer

    ### Measurements:
    - [Brakes](#/components/schema/Brake)
      - Information on the condition of brakes
      - This is currently limited to what percentage is remaining of the brake linings

    - [Fill levels](#/components/schema/FillLevel)
      - Fill level values for various fluids the vehicle needs to function
      - Available for AdBlue, engine oil, fuel, and washer fluid
      - A percentage remaining and/or a warning level is provided for each fluid

    - [Tires](#/components/schema/Tire)
      - Information on the condition of tires
      - Can include pressure (psi), temperature (celsius), air leakage rate (pa/s) and a warning level

    ## Typical use cases
    - Retrieve maintenance components to identify maintenance work that has to be carried out
    - Retrieve the condition of brake linings across a fleet to replace worn down brakes
    - Set up a custom component for checking the windshield of a vehicle, which will become due every 6 months

    ## Key terms
    - Asset: A vehicle, trailer or other asset
    - DueAt: Point in time at which a component will be due for maintenance
    - DueIn: Remaining number of kilometres before a component will be due for maintenance
  version: "1.2.0"
  contact:
    name: RIO Team MAN ServiceCare
    url: https://rio.cloud
    email: service-care@digitalhub.man
tags:
  - name: Components
    description: Parts of an asset, which will be due for maintenance at a future date and/or mileage.
  - name: Measurements
    description: Parts of an asset, for which a level can be measured continuously e.g. tire pressure.
  - name: Settings
    description: Settings defined by user associated to an asset e.g. pro active maintenance settings.
servers:
  - url: 'https://api.vehiclestate.rio.cloud'
paths:
  /brakes:
    get:
      summary: Returns list of brakes
      description: |
        Returns a list of brakes user has access to.
        If queried without an asset_id, all brakes for all assets assigned to the users workshop will be returned.
        If queried with a given asset_id the all brakes of a single asset, even if it is not assigned to the users workshop, will be returned.
      tags: [Measurements]
      operationId: getBrakes
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/X-Auth'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BrakeList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /maintenance-components:
    get:
      summary:  Returns maintenance components
      description: |
        Returns maintenance components the user has access to.
        If queried without an asset_id, maintenance components for all assets assigned to the users workshop will be returned.
        If queried with a given asset_id the maintenance components of a single asset, even if it is not assigned to the users workshop, will be returned.
      tags: [Components]
      operationId: getMaintenanceComponents
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/accept-language'
        - $ref: '#/components/parameters/X-Auth'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MaintenanceComponentList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /maintenance-components/{component_id}:
    patch:
      summary: Patch endpoint for workshop users to change maintenance-components
      description: |
        Interface to allow workshops to change the is_solved_by_customer flag for maintenance-components
      tags: [Components]
      parameters:
        - name: component_id
          in: path
          schema:
            $ref: '#/components/schemas/Id'
          required: true
        - $ref: '#/components/parameters/accept-language'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMaintenanceComponentRequestBody'
      responses:
        '200':
          description: Component updated successfully. The entire resource is returned.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MaintenanceComponent'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
  /custom-components:
    get:
      summary: Returns custom components
      description: |
        Returns custom components the user has access to.
        If queried without an asset_id, custom components for all assets assigned to the users workshop will be returned.
        If queried with a given asset_id the custom components of a single asset, even if it is not assigned to the users workshop, will be returned.
      tags: [Components]
      operationId: getCustomComponents
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/X-Auth'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CustomComponentList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /custom-components/{custom-component-id}:
    parameters:
      - $ref: '#/components/parameters/custom-component-id'
    get:
      summary: Returns a custom component
      description: |
        Returns the custom component with the customComponentId given if the user has access to.
      tags: [Components]
      operationId: getCustomComponent
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CustomComponent'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
    put:
      summary: Creates/Updates a custom component
      description: Createsnew custom component / Updates single fields of a custom component
      tags: [Components]
      operationId: updateCustomComponent
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/CustomComponent'
      responses:
        '200':
          description: Custom component has been updated
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CustomComponent'
        '201':
          description: Custom component has been created
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/CustomComponent'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.write
    delete:
      summary: Deletes a custom component
      description: Deletes a specific custom component
      tags: [Components]
      operationId: deleteCustomComponent
      responses:
        '204':
          description: Custom component has been deleted
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.write
  /fill-levels:
    get:
      summary: Returns a list of fill levels
      description: |
        Returns a list of all fill levels the user has access to.
        If queried without an asset_id, all fill levels for all assets assigned to the users workshop will be returned.
        If queried with a given asset_id the all fill levels of a single asset, even if it is not assigned to the users workshop, will be returned.
      tags: [Measurements]
      operationId: getFillLevels
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/X-Auth'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/FillLevelList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /tires:
    get:
      summary: Returns list of tires
      description: |
        Returns a list of tires the user has access to.
        If queried without an asset_id, all tires for all assets assigned to the users workshop will be returned.
        If queried with a given asset_id the all tires of a single asset, even if it is not assigned to the users workshop, will be returned.
      tags: [Measurements]
      operationId: getTires
      parameters:
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/X-Auth'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TireList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /pro-active-maintenance-settings-multiple:
    post:
      summary: Creates/Updates the pro-active maintenance settings for multiple given assetIds
      description: Creates or updates the pro-active maintenance settings when the RIO User changes the settings on FE.
      tags:
        [ Settings ]
      operationId: updateProActiveMaintenanceSettingsMultiple
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ProActiveMaintenanceSettingMultiple'
      responses:
        '204':
          description: Pro-active maintenance settings has been created/updated
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.write
  /pro-active-maintenance-settings/{asset_id}:
    get:
      summary: Returns the pro-active maintenance settings given an assetId
      description: |
        Returns the pro-active maintenance settings for the given assetId if the user has access to.
      tags:
        [Settings]
      operationId: getProActiveMaintenanceSettingsByAssetId
      parameters:
        - $ref: '#/components/parameters/asset_id_in_path'
        - $ref: '#/components/parameters/accept-language'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProActiveMaintenanceSetting'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
    put:
        summary: Creates/Updates the pro-active maintenance settings for a given assetId
        description: Creates or updates the pro-active maintenance settings when the RIO User changes the settings on FE.
        tags:
          [Settings]
        operationId: updateProActiveMaintenanceSettings
        parameters:
          - $ref: '#/components/parameters/asset_id_in_path'
        requestBody:
          required: true
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProActiveMaintenanceSetting'
        responses:
          '200':
            description: Pro-active maintenance settings has been created/updated
            content:
              'application/json':
                schema:
                  $ref: '#/components/schemas/ProActiveMaintenanceSetting'
          default:
            description: error occurred - see status code and problem object for more information.
            content:
              "application/problem+json":
                schema:
                  $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
        security:
          - oauth2:
              - maintenance.write
  /pro-active-maintenance-settings-status:
    get:
      summary: Returns the pro-active maintenance settings status of user assets
      description: |
        Returns the pro-active maintenance settings status of assets that the user has access to.
      tags:
        [ Settings ]
      operationId: getProActiveMaintenanceSettingsStatus
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProActiveMaintenanceStatusItems'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /pro-active-maintenance-settings-status/{asset_id}:
    get:
      summary: Returns the pro-active maintenance settings status of a given asset_id
      description: |
        Returns the pro-active maintenance settings status of the given asset_id if the user has access to.
      tags:
        [ Settings ]
      operationId: getProActiveMaintenanceSettingsStatusByAssetId
      parameters:
        - $ref: '#/components/parameters/asset_id_in_path'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ProActiveMaintenanceStatus'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /maintenance-states:
    get:
      summary: Returns the maintenance states of all assets assigned to the user
      description: |
        Returns the maintenance status of all assets assigned to the user
      tags:
        [ MaintenanceStates ]
      operationId: getMaintenanceStates
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MaintenanceStateList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /maintenance-states/{asset_id}:
    get:
      summary: Returns the maintenance state of a specific asset
      description: |
        Returns the maintenance state of a specific asset
      tags:
        [ MaintenanceStates ]
      operationId: getMaintenanceStatesByAssetId
      parameters:
        - $ref: '#/components/parameters/asset_id_in_path'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MaintenanceState'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /latest-events:
    get:
      summary: Returns the latest events of all assets assigned to the user
      description: |
        Returns the latest events of all assets assigned to the user
      tags:
        [ LatestEvents ]
      operationId: getLatestEvents
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/LatestEventList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /latest-events/{asset_id}:
    get:
      summary: Returns the latest event of a specific asset
      description: |
        Returns the latest event of a specific asset
      tags:
        [ LatestEvents ]
      operationId: getLatestEventsByAssetId
      parameters:
        - $ref: '#/components/parameters/asset_id_in_path'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/LatestEvent'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
  /service-keys:
    get:
      summary: Returns the list of the vehicle service-keys
      description: |
        Returns the list of the vehicle service-keys ( including current dashboard alarms and notices )
      tags:
        [ ServiceKeys ]
      operationId: getServiceKeys
      parameters:
        - $ref: '#/components/parameters/asset_id'
        - $ref: '#/components/parameters/accept-language'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ServiceKeysList'
        default:
          description: error occurred - see status code and problem object for more information.
          content:
            "application/problem+json":
              schema:
                $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
      security:
        - oauth2:
            - maintenance.read
components:
  schemas:
    LatestEventList:
      type: array
      items:
        $ref: '#/components/schemas/LatestEvent'
    LatestEvent:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/AssetId'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
    MaintenanceStateList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MaintenanceState'
      required:
        - items
    MaintenanceState:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/AssetId'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        status:
          $ref: '#/components/schemas/Status'
        components:
          $ref: '#/components/schemas/MaintenanceCategoryState'
        brakes:
          $ref: '#/components/schemas/MaintenanceCategoryState'
        fill_levels:
          $ref: '#/components/schemas/MaintenanceCategoryState'
      required:
        - asset_id
        - status
        - components
        - brakes
        - fill_levels
    MaintenanceCategoryState:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        count_normal:
          type: integer
          format: int32
        count_warning:
          type: integer
          format: int32
        count_danger:
          type: integer
          format: int32
        count_unknown:
          type: integer
          format: int32
      required:
        - status
        - count_normal
        - count_warning
        - count_danger
        - count_unknown
    Status:
      type: string
      example: normal
      x-extensible-enum:
        - normal
        - warning
        - danger
        - unknown
    AssetId:
      type: string
      format: uuid
    AxlePosition:
      type: string
      x-extensible-enum:
        - front_axle
        - rear_axle_1
        - rear_axle_2
        - rear_axle_3
        - rear_axle_4
        - rear_axle_5
        - rear_axle_6
        - rear_axle_7
        - rear_axle_8
        - rear_axle_9
        - rear_axle_10
        - rear_axle_11
        - rear_axle_12
        - reserve_wheels
      example: rear_axle_1
    Brake:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/Status'
        measurements:
          $ref: '#/components/schemas/BrakeMeasurements'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        asset_id:
          $ref: '#/components/schemas/AssetId'
        axle_position:
          $ref: '#/components/schemas/AxlePosition'
        axle_side:
          type: string
          x-extensible-enum:
            - left
            - right
          example: left
    BrakeList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Brake'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    BrakeMeasurements:
      type: object
      properties:
        brake_lining_percent:
          type: number
          format: float
          example: 86.4
    CustomComponent:
      type: object
      required:
          - name
          - asset_id
          - type
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
          example: Test crane structure
        status:
          $ref: '#/components/schemas/Status'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        type:
          type: string
          x-extensible-enum:
            - date
            - distance
          example: date
        recurrence:
          $ref: '#/components/schemas/Recurrence'
        asset_id:
          $ref: '#/components/schemas/AssetId'
        due_state:
          type: string
          x-extensible-enum:
            - next
            - almost_due
            - overdue
          example: next
        release_to_workshop:
          type: boolean
          example: true
      discriminator:
        propertyName: type
        mapping:
          date: '#/components/schemas/DateBasedCustomComponent'
          distance: '#/components/schemas/DistanceBasedCustomComponent'
    CustomComponentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CustomComponent'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    DateBasedCustomComponent:
      #       NOTE: Not used directly because discriminator based inheritance currently not provided by used code generator.
      #       As given here the correct inheritance model is reflected.
      #       Using the 'full' discriminator when provided will not introduce any changes to the actual API logic.
      #       Generics like CustomComponent will be replaced with the respective implementations e.g.
      #
      #       requestBody:
      #        required: true
      #        content:
      #          'application/json':
      #            schema:
      #              $ref: '#/components/schemas/CustomComponent'
      #
      #       will become
      #
      #       requestBody:
      #        required: true
      #        content:
      #          'application/json':
      #            schema:
      #              oneOf:
      #                - $ref: '#/components/schemas/DateBasedCustomComponent'
      #                - $ref: '#/components/schemas/DistanceBasedCustomComponent'
      #              discriminator:
      #                propertyName: type
      allOf:
        - $ref: '#/components/schemas/CustomComponent'
        - properties:
            almost_due_starts_at_date:
              type: 'string'
              format: 'date-time'
            due_at_date:
              type: 'string'
              format: 'date-time'
        - required:
          - almost_due_starts_at_date
          - due_at_date
    DistanceBasedCustomComponent:
      #      NOTE: See DateBasedCustomComponent
      allOf:
        - $ref: '#/components/schemas/CustomComponent'
        - properties:
            almost_due_starts_at_mileage_km:
              type: integer
              format: int32
            due_at_mileage_km:
              type: integer
              format: int32
        - required:
          - almost_due_starts_at_mileage_km
          - due_at_mileage_km
    DueAt:
      type: object
      properties:
        date:
          type: string
          format: date-time
          description: Point in time at which a component will be due for maintenance
        has_month_precision:
          type: boolean
          description: |
            If set to true, value always points to the beginning of a month (e.g. 1st of January),
            but indicates that the component will be due after this month. So the due state will only change
            at the end of the month.
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
    IsSolvedByCustomer:
      type: boolean
      description: >-
        Mark by the workshop whether the component was fixed/maintained by the customer already (probably based on a
        call by the workshop & customer). In such a case the component is typically in state DUE or OVERDUE which
        can be ignored by the workshop.
    DueIn:
      type: object
      properties:
        km:
          type: integer
          format: int32
          description: Remaining number of kilometres before a component will be due for maintenance
          example: 75000
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
    FillLevel:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/Status'
        measurements:
          $ref: '#/components/schemas/FillLevelMeasurements'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        type:
          type: string
          x-extensible-enum:
            - ad_blue
            - engine_oil
            - fuel
            - washer_fluid
          example: fuel
        asset_id:
          $ref: '#/components/schemas/AssetId'
    FillLevelList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FillLevel'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    FillLevelMeasurements:
      type: object
      properties:
        level_remaining_range:
          type: number
          format: float
          example: 3500.0
        level_percent:
          type: number
          format: float
          example: 41.6
        level_indicator_state:
          type: string
          x-extensible-enum:
            - normal
            - low
            - error
          example: normal
    Id:
      type: string
      format: uuid
      description: UUIDv4
    Limit:
      type: integer
      format: int32
      default: 100
      minimum: 1
      maximum: 1000000
    Link:
      type: object
      properties:
        href:
          type: string
          example: 'https://...'
    MaintenanceComponent:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/Status'
        type:
          $ref: '#/components/schemas/ComponentType'
        name:
          type: string
          description: |
            A human-readable name that identifies the type of maintenance component.
            Will be provided in the requested locale or the default locale if an unsupported locale is requested or the
            parameter is omitted
          example: Axle oil change
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        asset_id:
          $ref: '#/components/schemas/AssetId'
        due_state:
          type: string
          x-extensible-enum:
            - next
            - almost_due
            - overdue
            - not_initialised
          example: due
        due_at:
          $ref: '#/components/schemas/DueAt'
        due_in:
          $ref: '#/components/schemas/DueIn'
        release_to_workshop:
          type: boolean
          description: >-
            Decision by the fleet manager whether the workshop should schedule appointments for this component or not.
        is_solved_by_customer:
          $ref: '#/components/schemas/IsSolvedByCustomer'
    MaintenanceComponentList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MaintenanceComponent'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    MeasuredAt:
      type: object
      properties:
        mileage_km:
          type: number
          format: float
          example: 57255.48
        date:
          type: string
          format: date-time
    ProActiveMaintenanceComponent:
      type: object
      required:
        - type
        - proactive_maintenance_enabled
      properties:
        type:
          $ref: '#/components/schemas/ComponentType'
        name:
          type: string
          description: |
            A human-readable name that identifies the type of maintenance component.
            Will be provided in the requested locale or the default locale if an unsupported locale is requested or the
            parameter is omitted
          example: Axle oil change
        proactive_maintenance_enabled:
          type: boolean
          example: true
    ProActiveMaintenanceSetting:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/AssetId'
        components:
          type: array
          items:
            $ref: '#/components/schemas/ProActiveMaintenanceComponent'
        custom_components:
          type: boolean
      required: [ asset_id, components, custom_components ]
    ProActiveMaintenanceSettings:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProActiveMaintenanceSetting'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    ProActiveMaintenanceSettingMultiple:
      type: object
      required:
        - asset_ids
        - maintenance_components
        - custom_components
      properties:
        asset_ids:
          type: array
          items:
            $ref: '#/components/schemas/AssetId'
        maintenance_components:
          type: boolean
        custom_components:
          type: boolean
    ProActiveMaintenanceStatus:
      type: object
      properties:
        asset_id:
          $ref: '#/components/schemas/AssetId'
        status:
          type: string
          description: status based on components and custom-components settings.
            If all components and custom-components settings are true, the status should be ON.
            If all components and custom-components settings are false, the status should be OFF.
            Otherwise the status should be PARTIALLY_ON.
          x-extensible-enum:
            - on
            - partially_on
            - off
          example: partially_on
      required:
        - asset_id
        - status
    ProActiveMaintenanceStatusItems:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProActiveMaintenanceStatus'
      required:
        - items
    Recurrence:
      description: 'Interval based on distance or time at which maintenance needs to performed.'
      type: object
      required: [interval, interval_type]
      properties:
        interval:
          type: integer
          format: int32
          example: 6
        interval_type:
          type: string
          x-extensible-enum:
            - distance
            - year
            - month
            - week
          example: month
    ResourceListLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Tire:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        measurements:
          $ref: '#/components/schemas/TireMeasurements'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
        axle_position:
          $ref: '#/components/schemas/AxlePosition'
        axle_side:
          type: string
          x-extensible-enum:
            - left_inner
            - left_outer
            - right_inner
            - right_outer
          example: left_outer
        asset_id:
          $ref: '#/components/schemas/AssetId'
    TireMeasurements:
      type: object
      properties:
        pressure_kpa:
          type: integer
          format: int32
          description: Tire pressure in kPa (KiloPascal)
          example: 800
        temperature_celsius:
          type: number
          format: float
          description: Inside tire temperature
        air_leakage_rate_pas:
          type: number
          format: float
          description: Air leakage rate in pa/s
        threshold_detection:
          type: string
          x-extensible-enum:
            - extreme_over_pressure
            - over_pressure
            - no_warning_pressure
            - under_pressure
            - extreme_under_pressure
            - not_defined
            - error_indicator
            - not_available
          example: no_warning_pressure
    TireList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tire'
        _links:
          $ref: '#/components/schemas/ResourceListLinks'
    ComponentType:
      type: string
      example: axle_oil_change
      x-extensible-enum:
        - air_dryer
        - air_filter
        - axle_oil_change
        - brake_pads
        - clutch_lining
        - cooling_component
        - cooling_system
        - customer_fixed_inspection_1
        - customer_fixed_inspection_2
        - customer_fixed_inspection_3
        - engine_oil_change
        - fms_customer_service
        - gearbox_oil_change
        - hydrodrive
        - hydrostatic_fan
        - initial_service
        - inspection_i
        - legal_inspection_1
        - legal_inspection_2
        - legal_inspection_3
        - legal_inspection_4
        - legal_inspection_5
        - level_fuel
        - maintenance_interval_calculator
        - refrigerant_compressor
        - retarder_oil_change
        - s6
        - steering
        - steering_front_axles
        - steering_rear_axle
        - torque_converter_clutch
        - transfer_case_oil_change
        - valve_clearance
    PatchMaintenanceComponentRequestBody:
      type: object
      properties:
        is_solved_by_customer:
          $ref: '#/components/schemas/IsSolvedByCustomer'
    ServiceKeysList:
      type: array
      items:
        $ref: '#/components/schemas/ServiceKey'
    ServiceKey:
      type: object
      required: [ tss_id, display_id, display_priority, name, status, transmitted_at, occurred_at ]
      properties:
        tss_id:
          type: string
          description: |
            The TSS-Id in hexadecimal format 0x020203XXXX
        display_id:
          type: string
          description: |
            The Display-Id as defined in the ServiceKey_Decoder file (0xXXXX)
        display_priority:
          type: number
          description: |
            The system defined priority for ServiceKeys alarms as defined in the ServiceKey_Decoder file.
        name:
          type: string
          description: |
            A human-readable name that identifies the service key.
            Will be provided in the requested locale or the default locale if an unsupported locale is requested or the
            parameter is omitted
          example: Oil overfill warning
        status:
          $ref: '#/components/schemas/Status'
        transmitted_at:
          $ref: '#/components/schemas/TransmittedAt'
        occurred_at:
          $ref: '#/components/schemas/OccurredAt'
    TransmittedAt:
      type: object
      required: [ date ]
      properties:
        date:
          type: string
          format: date-time
    OccurredAt:
      type: object
      description: A date at which the warning occurred at
      required: [ date ]
      properties:
        date:
          type: string
          format: date-time
  parameters:
    after:
      in: query
      name: after
      description: |
        The cursor that points to the (not included) beginning of the requested page
      schema:
        type: string
    asset_id:
      in: query
      name: asset_id
      description: asset_id
      schema:
        type: string
    asset_id_in_path:
      name: asset_id
      in: path
      schema:
        type: string
      required: true
    before:
      in: query
      name: before
      description: |
        The cursor that points to the (not included) end of the requested page
      schema:
        type: string
    custom-component-id:
      name: custom-component-id
      in: path
      required: true
      schema:
        type: string
        description: UUIDv4
        format: uuid
    limit:
      in: query
      name: limit
      description: |
        Limit page size
      schema:
        $ref: '#/components/schemas/Limit'
    X-Auth:
      in: header
      name: X-Auth
      description: Token received in case of vin-search
      schema:
        type: string
    accept-language:
      name: Accept-Language
      description: |
        Specifies the desired language variant for the response where localization is supported
      required: false
      in: header
      schema:
        type: string
        default: 'en-GB'
        description: |
          Combination of [ISO 639-1 language code](http://www.loc.gov/standards/iso639-2/php/code_list.php)
          and [ISO 3166-alpha2 country code](https://www.iso.org/obp/ui/#search/code/)
          For example, en-GB represents British English.
        x-extensible-enum:
          - cs-CZ
          - da-DK
          - de-DE
          - en-GB
          - es-ES
          - et-EE
          - fr-FR
          - it-IT
          - lt-LT
          - lv-LV
          - nl-NL
          - nb-NO
          - pl-PL
          - pt-PT
          - sk-SK
          - sl-SI
          - sv-SE
          - bg-BG
          - hr-HR
          - fi-FI
          - hu-HU
          - ro-RO
          - el-GR
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://auth.iam.rio.cloud/oauth/token'
          scopes:
            maintenance.write: Write access
            maintenance.read: Read access
