openapi: 3.0.0

x-zally-ignore:
  - 224

info:
  title: Driving Time API
  version: 2.3.1
  description: |
    An API that provides driver working activity data as snapshot and aggregated data enriched with tachograph data, information
    on infringements of legal regulations, on shift times and working times.

    ## Taxonomy

    * An `activity` is the working state of a driver out of the `activity types`: `driving`, `working`, `resting` and `available`. 
      Activities are only provided in periods, in which  the underlying raw data has been recorded in the vehicles. This is typically not the case when the vehicle is switched off.
    * A `sample` represents a snapshot of tacho data and contains driving and resting details, Eu-infringements and Eu-shift-times
    * `Driving and resting details` include all driving and resting times which are fetchable from a tachograph device
    * `Working times` include the daily/weekly working times of a driver and 
      additional related info
    * `EU-infringements` are detected on the basis EU regulations and represent the 
      result of calculations on the available driving
    * `EU-working-time-infringements` are working time related infringements 
      determined based on the underlying EU regulations
    * `EU-shift-times` represent shift times of a driver based on EU regulations and the available driving and
    resting details

    ## Typical use cases

    Data is available in multiple forms: As aggregated driver data (activities), single snapshot (samples) data and working times data. All types of data
    can be retrieved either for a whole fleet or only a single driver. Furthermore a timeframe can be specified for all queries related to activities and samples.

    * Retrieve a list of latest samples within a given time frame for all drivers in a fleet
    * Retrieve the latest sample within a given time frame for a specified driver
    * Retrieve all driver-activities within a given time frame for all drivers in a fleet
    * Retrieve the driver activities within a given timeframe for a specified driver
    * Retrieve a list of current working times for all drivers in a fleet
    * Retrieve the current working times for a specified driver
    
    ### Data retention times
    
    When making requests, keep in mind the specific retention times, after the expiration of which data will not be available via the API:
    * 14 days for driving time samples and working times
    * 90 days for activities data

    ## Example queries

    get latest sample in specified time frame for each driver in your account
    ```
    GET /drivers?from=2020-05-12T12%3A00%3A00.000Z&to=2020-05-12T13%3A30%3A00.000Z
    ```
    get most recent sample from specified driver
    ```
    GET /drivers/f2371605-dedb-480a-85d4-5a4f8f17d57c
    ```
    get all driver activities starting from given time until now in your account
    ```
    GET /drivers-activities?from=2020-05-12T12%3A00%3A00.000Z
    ```
    get all driver activities older than given time for a specified driver
    ```
    GET /drivers/f2371605-dedb-480a-85d4-5a4f8f17d57c/activities?to=2020-05-12T13%3A30%3A00.000Z
    ```
    get all driver activities for the specified driver after the given id (pagination). Instead of manually assembling the query it is recommended to use the link provided in previous page under `_links.next.href`.
    ```
    GET /drivers/f2371605-dedb-480a-85d4-5a4f8f17d57c/activities?after=733904dc-6f7b-4030-9543-9a06ab0815e2
    ```
    get current working times for each driver in your account
    ```
    GET /drivers-working-times
    ```
    get current working times for a specified driver
    ```
    GET /drivers/f2371605-dedb-480a-85d4-5a4f8f17d57c/working-times

  contact:
    name: RIO Timed
    url: https://rio.cloud
    email: rio_team_transport_two@rio.cloud
  x-api-id: 587648d7-a3c8-44bb-b74e-abebb4c0da21
  x-audience: external-partner

servers:
  - url: https://api.drivingtime.rio.cloud

tags:
  - name: Driving Time
    description: Latest driving and resting times for drivers
  - name: Driver Activity
    description: Aggregated history of driver activity changes
  - name: Driver Working Times
    description: Current working times for drivers
paths:
  /drivers:
    x-zally-ignore:
      - '134' # MUST Pluralize Resource Names
    get:
      tags:
        - Driving Time
      summary: Get latest sample for each driver
      description: ""
      operationId: getDrivingTimesList
      parameters:
        - $ref: '#/components/parameters/from_for_samples'
        - $ref: '#/components/parameters/to_for_samples'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limitDrivers'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrivingTimeSamplesList'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read
  "/drivers/{driver-id}":
    x-zally-ignore:
      - '134' # MUST Pluralize Resource Names
    get:
      tags:
        - Driving Time
      summary: Get latest sample for a specific driver
      operationId: getSamplesForDriver
      parameters:
        - $ref: '#/components/parameters/driver_id_path'
        - $ref: '#/components/parameters/from_for_samples'
        - $ref: '#/components/parameters/to_for_samples'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrivingTimeSample'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read
  /drivers-activities:
    get:
      tags:
        - Driver Activity
      summary: Get the driver activities of all drivers
      description: ""
      operationId: getDriverActivities
      parameters:
        - $ref: '#/components/parameters/from_for_activities'
        - $ref: '#/components/parameters/to_for_activities'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limitActivities'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverActivitiesList'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read
  "/drivers/{driver-id}/activities":
    get:
      tags:
        - Driver Activity
      summary: Get the driver activities for a given driver
      operationId: getDriverActivitiesForDriver
      parameters:
        - $ref: '#/components/parameters/driver_id_path'
        - $ref: '#/components/parameters/from_for_activities'
        - $ref: '#/components/parameters/to_for_activities'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limitActivities'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverActivitiesList'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read
  /drivers-working-times:
    get:
      tags:
        - Driver Working Times
      summary: Get the current working times for all drivers
      description: ""
      operationId: getDriverWorkingTimes
      parameters:
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limitDrivers'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverWorkingTimesList'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read
  "/drivers/{driver-id}/working-times":
    get:
      tags:
        - Driver Working Times
      summary: Get the current working time for a given driver
      operationId: getDriverWorkingTimesForDriver
      parameters:
        - $ref: '#/components/parameters/driver_id_path'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverWorkingTime'
        default:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
      security:
        - oauth2:
            - driving-time.read

components:
  parameters:
    after:
      in: query
      name: after
      required: false
      description: Return next page after given id
      schema:
        type: string
    limitDrivers:
      in: query
      name: limit
      description: |
        Limit page size
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 100
    limitActivities:
      in: query
      name: limit
      description: |
        Limit page size
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 10000
        default: 1000
    from_for_activities:
      in: query
      name: from
      schema:
        type: string
        format: date-time
      description: |
        Start date (inclusive) for time range query (e.g. 2019-01-01T12:00:00.000Z). Needs to be earlier than the time specified in "to".
        If "from" is not given, then all data from the oldest dataset onwards is taken into account for the query.
    to_for_activities:
      in: query
      name: to
      schema:
        type: string
        format: date-time
      description: |
        End date (inclusive) for time range query (e.g. 2019-01-01T12:00:00.000Z). Needs to be later than the time specified in "from".
        If "to" is not given, then all data up to the newest dataset is taken into account for the query.
    from_for_samples:
      deprecated: true
      in: query
      name: from
      schema:
        type: string
        format: date-time
      description: |
        Start date (inclusive) for time range query (e.g. 2019-01-01T12:00:00.000Z). Needs to be earlier than the time specified in "to".
        If "from" is not given, then all data from the oldest dataset onwards is taken into account for the query.
    to_for_samples:
      deprecated: true
      in: query
      name: to
      schema:
        type: string
        format: date-time
      description: |
        End date (inclusive) for time range query (e.g. 2019-01-01T12:00:00.000Z). Needs to be later than the time specified in "from".
        If "to" is not given, then all data up to the newest dataset is taken into account for the query.
    driver_id_path:
      in: path
      name: driver-id
      required: true
      description: |
        RIO Driver Id
      schema:
        type: string
  schemas:

    DrivingTimeSamplesList:
      type: object
      properties:
        _links:
          $ref: "#/components/schemas/ResourceListLinks"
        items:
          type: array
          items:
            $ref: '#/components/schemas/DrivingTimeSample'
      required:
        - _links
        - items

    DrivingTimeSample:
      type: object
      properties:
        sample_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: Id of the sample
        driver_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: RIO Driver Id
        asset_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: Source asset (vehicle) of the data
        identification:
          type: string
          description: Identification number of the driver card
          example: D MAN 00028 00
        identification_type:
          type: string
          x-extensible-enum:
            - EU_TACHOGRAPH_CARD
        sample_date_time:
          type: string
          format: date-time
          description: Timestamp (UTC) of the snapshot of the driver state
          example: '2019-01-01T12:00:00.000Z'
        activity_type:
          $ref: "#/components/schemas/ActivityType"
        driving_and_resting_details:
          $ref: "#/components/schemas/DrivingAndRestingDetails"
        eu_shift_times:
          $ref: '#/components/schemas/EuShiftTime'
        eu_infringements:
          type: array
          items:
            $ref: '#/components/schemas/EuInfringement'
      required:
        - sample_id
        - driver_id
        - asset_id
        - identification
        - identification_type
        - sample_date_time
        - activity_type

    DriverActivitiesList:
      type: object
      properties:
        _links:
          $ref: "#/components/schemas/ResourceListLinks"
        items:
          type: array
          items:
            $ref: '#/components/schemas/DriverActivity'
      required:
        - _links
        - items

    DriverActivity:
      type: object
      properties:
        activity_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: Id of the activity
        driver_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: RIO Driver Id
        asset_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: Source asset (vehicle) of the data
        identification:
          type: string
          description: Identification number of the driver card
          example: D MAN 00028 00
        identification_type:
          type: string
          x-extensible-enum:
            - EU_TACHOGRAPH_CARD
        activity_type:
          $ref: "#/components/schemas/ActivityType"
        start:
          type: string
          format: date-time
          description: Start Timestamp (UTC) of the activity
          example: '2019-01-01T12:00:00.000Z'
        end:
          type: string
          format: date-time
          description: End Timestamp (UTC) of the activity
          example: '2019-01-01T12:00:00.000Z'
      required:
        - activity_id
        - sample_id
        - driver_id
        - asset_id
        - identification
        - identification_type
        - type
        - start
        - end

    DriverWorkingTimesList:
      type: object
      properties:
        _links:
          $ref: "#/components/schemas/ResourceListLinks"
        items:
          type: array
          items:
            $ref: '#/components/schemas/DriverWorkingTime'
      required:
        - _links
        - items

    DriverWorkingTime:
      type: object
      properties:
        driver_id:
          type: string
          example: 329bdc49-1859-4144-ad14-ac5da764abf5
          description: RIO Driver Id
        latest_data_at:
          type: string
          format: date-time
          description: Timestamp (UTC) when the working times of the driver have been updated the last time
          example: '2019-01-01T12:00:00.000Z'
        current_daily_working_time:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The working time of the current day.
        remaining_daily_working_time:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The remaining working time for the current day.
        current_weekly_working_time:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The working time of the current week.
        remaining_weekly_working_time:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The remaining working time for the current week.
        ddd_data_until:
          type: string
          format: date-time
          description: Indicates the date time until which data from uploaded DDD 
                       files has been taken into account
          example: '2019-01-01T12:00:00.000Z'
        current_working_time_infringements:
          type: array
          items:
            $ref: '#/components/schemas/EuWorkingTimeInfringement'
      required:
        - driver_id
        - identification
        - identification_type
        - latest_data_at

    DrivingAndRestingDetails:
      description: Tachograph data based on https://www.iso.org/standard/57315.html
      type: object
      properties:
        specification:
          type: string
          description: |
            Identifier for the specification the data adheres to
          x-extensible-enum:
            - ISO_16844_7:2015
            - ISO_16844_7:2004
        source:
          type: string
          description: Free text identifier of the source for the data
          example: SE5000
        continuous_driving_time:
          type: integer
          format: int32
          description: This parameter shall be computed as the current accumulated driving
            times of a particular driver, as defined by legal regulation. (Given in minutes)
        cumulative_break_time:
          type: integer
          format: int32
          description: This parameter shall indicate the uninterrupted break time for
            driver 1 as defined by legal regulation. (Given in minutes)
        current_duration_of_selected_activity:
          type: integer
          format: int32
          description: This parameter shall indicate the current duration of the selected
            activity, since selected, and which may be the current driving
            period, availability period, rest period, or work period. (Given in minutes)
        cumulated_driving_time_previous_and_current_week:
          type: integer
          format: int32
          description: This parameter shall be computed as the current accumulated driving
            times of driver 1 (driver) for the previous and the current week. (Given in minutes)
        end_of_last_daily_rest_period:
          type: integer
          format: int64
          description: This parameter shall be the end of the last daily rest period of
            driver 1, as computed by the tachograph using driver 1 card data. (Given as Unix timestamp)
        end_of_last_weekly_rest_period:
          type: integer
          format: int64
          description: This parameter shall be the end of the last weekly rest period of
            driver 1, as computed by the tachograph using driver 1 card data. (Given as Unix timestamp)
        end_of_second_last_weekly_rest_period:
          type: integer
          format: int64
          description: This parameter shall be the end of the second last weekly rest
            period of driver 1, as computed by the tachograph using driver 1
            card data. (Given as Unix timestamp)
        current_daily_driving_time:
          type: integer
          format: int32
          description: This parameter shall be the current daily driving time of driver 1,
            as computed by the tachograph using driver 1 card data. (Given in minutes)
        current_weekly_driving_time:
          type: integer
          format: int32
          description: This parameter shall be the current weekly driving time of driver 1,
            as computed by the tachograph using driver 1 card data. (Given in minutes)
        time_left_until_new_daily_rest_period:
          type: integer
          format: int32
          description: This parameter shall be the calendar time left until driver 1 shall
            start a new daily rest period. (Given in minutes)
        time_left_until_new_weekly_rest_period:
          type: integer
          format: int32
          description: This parameter shall be the calendar time left until driver 1 shall
            start a new weekly rest period. (Given in minutes)
        number_of_times_9h_daily_driving_times_exceeded:
          type: integer
          format: int32
          description: This parameter shall be the number of times the driver exceeded 9 h
            daily driving time in the current week.
        cumulative_uninterrupted_rest_time:
          type: integer
          format: int32
          description: This parameter shall be the cumulative uninterrupted rest period for
            driver 1 since last fulfilled daily rest. It shall be incremented
            each minute of uninterrupted rest time. (Given in minutes)
        minimum_daily_rest:
          type: integer
          format: int32
          description: This parameter shall be the minimum daily rest the driver 1 needs to
            do to fulfil an on-going or approaching daily rest period. (Given in minutes)
        minimum_weekly_rest:
          type: integer
          format: int32
          description: This parameter shall be the minimum weekly rest the driver 1 needs
            to do to fulfil an on-going or approaching weekly rest period. It
            shall be set to regular or reduced weekly rest period plus
            compensation hours, if any. (Given in minutes)
        maximum_daily_period:
          type: integer
          format: int32
          description: This parameter shall be set to the maximum allowed calendar time
            between the end of two daily rests (the daily period) for driver 1. (Given in hours)
        maximum_daily_driving_time:
          type: integer
          format: int32
          description: This parameter shall be the maximum daily driving time for driver 1. (Given in hours)
        number_of_used_reduced_daily_rest_periods:
          type: integer
          format: int32
          description: This parameter shall be the number of times the driver has used
            reduced daily rest times since previous weekly rest period.
        remaining_current_driving_time:
          type: integer
          format: int32
          description: This parameter shall be the maximum remaining driving time left to
            next required break/rest according to what is defined by regulation. (Given in minutes)
        remaining_driving_time_on_current_shift:
          type: integer
          format: int32
          description: This parameter shall be the maximum remaining driving time left on
            current day for driver 1. (Given in minutes)
        remaining_driving_time_of_current_week:
          type: integer
          format: int32
          description: This parameter shall be set to the maximum remaining driving time
            left of current week for driver 1. (Given in minutes)
        remaining_2_weeks_driving_time:
          type: integer
          format: int32
          description: This parameter shall be set to the maximum remaining driving time
            left of current week and next week for driver 1. (Given in minutes)
        time_left_until_next_driving_period:
          type: integer
          format: int32
          description: This parameter shall be set to the minimum time left until driver 1
            can start next driving period. (Given in minutes)
        duration_of_next_driving_period:
          type: integer
          format: int32
          description: This parameter shall be set to the maximum duration of next driving
            period for driver 1. (Given in minutes)
        duration_of_next_break_rest:
          type: integer
          format: int32
          description: This parameter shall be set to the minimum duration of next
            break/rest for driver 1. (Given in minutes)
        remaining_time_of_current_break_rest:
          type: integer
          format: int32
          description: This parameter shall be set to the remaining time of current rest or
            break period for driver 1. (Given in minutes)
        remaining_time_until_next_break_or_rest:
          type: integer
          format: int32
          description: This parameter shall be set to the remaining time until next rest or
            break period for driver 1. (Given in minutes)
        open_compensation_in_the_last_week:
          type: integer
          format: int32
          description: This parameter shall be set to the open compensation in the last
            week for driver 1. (Given in minutes)
        open_compensation_in_week_before_last:
          type: integer
          format: int32
          description: This parameter shall be set to the open compensation in the week
            before last for driver 1. (Given in minutes)
        open_compensation_in_2nd_week_before_last:
          type: integer
          format: int32
          description: This parameter shall be set to the open compensation in the 2nd week
            before last for driver 1. (Given in minutes)
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'

    AdditionalInformation:
      description: Additional tachograph data based on https://www.iso.org/standard/57315.html
      type: object
      properties:
        remaining_10h_driving_times:
          type: integer
          format: int32
          description: |
            This parameter shall indicate the remaining 10 h driving times.
            Operating range: 0 to 2
        remaining_reduced_daily_rest_periods:
          type: integer
          format: int32
          description: |
            This parameter shall indicate the remaining reduced daily rest periods.
            Operating range: 0 to 3
        unknown_periods:
          type: boolean
          description: |
            0 — no unknown periods
            1 — At least one unknown period is considered in the recommendation for the remaining driving
        data_availability_on_driver_card:
          type: boolean
          description: |
            0 — Sufficient data on the driver card is available
            1 — No sufficient data on the driver card
        weekly_rest_period_calculation_status:
          type: boolean
          description: |
            0 — The weekly rest periods calculation is disabled.
            1 — The weekly rest periods calculation is enabled.
        multi_manning_detection_status:
          type: boolean
          description: |
            0 — Single driver for the current shift is detected.
            1 — Multi-manning for the current shift is detected.
        time_overlap_detection_status:
          type: boolean
          description: |
            0 — No significant time overlaps in used driver activities are detected.
            1 — A significant time overlap in used driver activities is detected.

    EuInfringement:
      description: |
        An infringement according to <a href="https://eur-lex.europa.eu/eli/reg/2006/561/2015-03-02">EU Regulation (EC) No 561/2006</a>.
      type: object
      properties:
        type:
          type: string
          description: |
            The type of an infringement according to
            [EU Regulation (EC) No 561/2006](https://eur-lex.europa.eu/eli/reg/2006/561/2015-03-02)
            and the country-specific implementations of
            [EU Directive 2002/15/EC](https://eur-lex.europa.eu/eli/dir/2002/15/oj).

            According to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj)
            the Type represents the following numbers:

            Annex III:
            * exceeded_current_driving_time: c.f. Section C1 - C3
            * exceeded_daily_driving_time: c.f. Section B1 - B4
            * exceeded_daily_driving_time_extended: c.f. Section B5 - B8
            * exceeded_weekly_driving_time: c.f. Section B9 - B12
            * exceeded_weekly_driving_time_fortnightly: c.f. Section B13 - B16
            * insufficient_daily_rest_regular: c.f. Section D1 - D3

            In addition to that, three more types were introduced:
            * status_cumulated_rest_time = indicates the value and deviation of the cumulated rest time (target value 45 min)
            * exceeded_number_of_daily_driving_time_extended = indicated the number, how often the driver exceeded
              the target daily driving time in the current week (limit 2 times)
            * exceeded_number_of_reduced_daily_rest_time = indicates the number, how often the driver fell below the
              target daily rest time in the current week (limit 3 times)

          x-extensible-enum:
            - EXCEEDED_CURRENT_DRIVING_TIME
            - EXCEEDED_DAILY_DRIVING_TIME
            - EXCEEDED_DAILY_DRIVING_TIME_EXTENDED
            - EXCEEDED_WEEKLY_DRIVING_TIME
            - EXCEEDED_WEEKLY_DRIVING_TIME_FORTNIGHTLY
            - INSUFFICIENT_DAILY_REST_REGULAR
            - STATUS_CUMULATED_REST_TIME
            - EXCEEDED_NUMBER_OF_DAILY_DRIVING_TIME_EXTENDED
            - EXCEEDED_NUMBER_OF_REDUCED_DAILY_REST_TIME
        category:
          description: |
            The category of the infringement. A category is a group of types.

            According to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj) the Type represents the following numbers:

            Annex III:
            * daily_driving: c.f. Section B1 - B8
            * weekly_driving: c.f. Section B9 - B12
            * weekly_driving_fortnightly: c.f. Section B13 - B16
            * current_driving: c.f. Section C1 - C3
            * daily_rest: c.f. Section D1 - D12
          type: string
          x-extensible-enum:
            - CURRENT_DRIVING
            - DAILY_DRIVING
            - WEEKLY_DRIVING
            - WEEKLY_DRIVING_FORTNIGHTLY
            - DAILY_REST
        target:
          description: The allowed maximum or required minimum duration of the infringement related activity to cause no infringement.
          type: string
        actual:
          description: The actual duration of the infringement related activity.
          type: string
        deviation:
          description: The deviation from target to actual.
          type: string
        level:
          description: |
            The severity of an infringement according to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj).
            * minor: MI = minor infringements
            * serious: SI = serious infringements
            * very_serious: VSI = very serious infringements
            * most_serious: MSI = most serious infringements

            In addition to that, three more levels were introduced, to indicate a state before an actual infringement occurs
            * info = provides only the information on the current deviation between the actual and the target values
            * warn = indicates that an infringement would have occurred, unless the tolerated number of this type of infringement
              is not yet reached (i.e. the daily driving timed exceeded 9h, but this happened not more than twice in the current week)
            * alert = indicates that an infringement has occurred, but the tolerated number of this type of infringement
              is not yet reached and the actual infringement level is covered by the corresponding infringement type
              (i.e. the daily driving timed exceeded 10h, but an exceeding of 9h happened not more than twice in the current week,
              and therefore, the infringement level is given by the exceeded_daily_driving_time_extended type)
          x-extensible-enum:
            - INFO
            - WARN
            - ALERT
            - MINOR
            - SERIOUS
            - VERY_SERIOUS
            - MOST_SERIOUS
          type: string
      required:
        - type
        - category
        - level
        - deviation
        - actual
        - target

    EuWorkingTimeInfringement:
      description: |
        A working time related infringement according to <a href="https://eur-lex.europa.eu/eli/reg/2006/561/2015-03-02">EU Regulation (EC) No 561/2006</a> and the country-specific implementations of <a href="https://eur-lex.europa.eu/eli/dir/2002/15/oj">EU Directive 2002/15/EC</a>.
      type: object
      properties:
        type:
          type: string
          description: |
            The type of a working time related infringement according to
            [EU Regulation (EC) No 561/2006](https://eur-lex.europa.eu/eli/reg/2006/561/2015-03-02)
            and the country-specific implementations of
            [EU Directive 2002/15/EC](https://eur-lex.europa.eu/eli/dir/2002/15/oj).

            According to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj)
            the Type represents the following numbers:
          
            Annex I:
            * exceeded_weekly_working_time_on_average: c.f. Section 3.1. - 3.2
            * exceeded_weekly_working_time: c.f. Section 3.3. - 3.4
            * exceeded_working_time_period: c.f. Section 3.5. - 3.8
            * insufficient_daily_working_time_breaks: c.f. Section 3.5. - 3.8
            * exceeded_nightly_working_time: c.f. Section 3.9. - 3.10.
            * exceeded_daily_working_time: based on country specific regulations

          x-extensible-enum:
            - EXCEEDED_WEEKLY_WORKING_TIME_ON_AVERAGE
            - EXCEEDED_WEEKLY_WORKING_TIME
            - EXCEEDED_WORKING_TIME_PERIOD
            - INSUFFICIENT_DAILY_WORKING_TIME_BREAKS
            - EXCEEDED_NIGHTLY_WORKING_TIME
            - EXCEEDED_DAILY_WORKING_TIME
        category:
          description: |
            The category of the infringement. A category is a group of types.

            According to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj) the Type represents the following numbers:
            
            Annex I:
            * weekly_working_on_average: c.f. Section 3.1. - 3.2
            * weekly_working: c.f. Section 3.3. - 3.4
            * current_working: c.f. Section 3.5. - 3.8
            * daily_working_breaks: c.f. Section 3.5. - 3.8
            * nightly_working: c.f. Section 3.9. - 3.10
            * daily_working: based on country specific regulations
          type: string
          x-extensible-enum:
          - WEEKLY_WORKING_ON_AVERAGE
          - WEEKLY_WORKING
          - CURRENT_WORKING
          - DAILY_WORKING_BREAKS
          - NIGHTLY_WORKING
          - DAILY_WORKING
        target:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The allowed maximum or required minimum duration of the infringement related activity to cause no infringement.
        actual:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The actual duration of the infringement related activity.
        deviation:
          type: string
          format: duration
          example: 'PT12H30M17S'
          description: The deviation from target to actual.
        level:
          description: |
            The severity of an infringement according to [EU Regulation (EU) 2016/403](https://eur-lex.europa.eu/eli/reg/2016/403/oj).
            * minor: MI = minor infringements
            * serious: SI = serious infringements
            * very_serious: VSI = very serious infringements
            * most_serious: MSI = most serious infringements
          x-extensible-enum:
            - MINOR
            - SERIOUS
            - VERY_SERIOUS
            - MOST_SERIOUS
          type: string
      required:
        - type
        - category
        - level
        - deviation
        - actual
        - target

    EuShiftTime:
      description: Start time, end time, current and maximum duration of a shift of a driver.
      type: object
      properties:
        shift_start:
          type: string
          format: date-time
          description: Start time (UTC) of the current shift of a driver.
          example: '2019-01-01T12:00:00.000Z'
        shift_end:
          type: string
          format: date-time
          description: Expected end time (UTC) of the current shift of a driver.
          example: '2019-01-01T12:00:00.000Z'
        shift_time:
          type: integer
          format: int32
          description: |
            Current duration of the current shift of a driver, given in minutes.
        shift_max:
          type: integer
          format: int32
          description: |
            Maximum possible duration of the current shift of a driver, given in minutes.
            For EU, this value can be either 13h or 15h in minutes.
            In general, shift_max is 15h, then shift_time might exceed shift_max twice a week.
            If this case has occurred, shift_max is 13h in minutes.
        shift_exceeded:
          type: boolean
          description: Indicates, that shift_time > shift_max
        remaining_shift_time:
          type: integer
          format: int32
          description: |
            Difference between shift_max and shift_time
        daily_rest_warning:
          type: boolean
          description: Indicates, that the maximum number of exceedances of shift_time has occurred
      required:
        - daily_rest_warning
        - remaining_shift_time
        - shift_exceeded
        - shift_max
        - shift_time
        - shift_end
        - shift_start

    ActivityType:
      type: string
      x-extensible-enum:
        - RESTING
        - AVAILABLE
        - WORKING
        - DRIVING

    ResourceListLinks:
      type: object
      properties:
        self:
          $ref: "#/components/schemas/Link"
        next:
          $ref: "#/components/schemas/Link"
      readOnly: true
      required:
        - self

    Link:
      type: object
      properties:
        href:
          type: string
          example: "https://..."
      readOnly: true
      required:
        - href

  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://auth.iam.rio.cloud/oauth/token'
          scopes:
            driving-time.read: Read access to driving time data
