api-b2c.yaml

openapi: 3.0.0
servers:
  - url: 'https://api.mpsa.com/api/connectedcar/v2'
info:
  version: '4.17.2'
  title: Groupe PSA Connected Car B2C API
  license:
    name: Groupe PSA Licence
    url: 'https://www.psa-peugeot-citroen.com/'
  description: >
   
    # Introduction:

    This is the description of the *Groupe PSA Connected Car B2C API*. 
    This specification is written in **OpenAPI Specification version 3** and can
    be displayed using [ReDoc](https://github.com/Rebilly/ReDoc) or
    [Swagger](http://swagger.io).
      This REST API allows  applications to fetch data from the connected Vehicles data  platform.
    
    ---
    
    # Authentication:
    
      PSA Connected Car APIs uses the [OAuth  2.0](https://tools.ietf.org/html/rfc6749) protocol for authentication and
      authorization. Any applications require a valid [Access Token](https://tools.ietf.org/html/rfc6749#section-1.4) to access to user data.
      The Implicit Grant Type is used to get the access token.
      
    ---
    
    # Scopes:
    
      ## Filtering Scopes
      - When the API caller requests a set of scopes. The owner may not grant access to all of the requested scopes, so the application will have to adapt to the restricted access or request for a larger set of scopes again.
      - API backend will deliver the data related to the granted scopes only. 
      - If no scope has been granted with the caller token then an unauthorized error will be returned.
          
        _If for example the API caller requests for "aggregated telemetry" or "trip" without having the "location" scope, then the resource data returned will not have the vehicle's position but only other data that will satisfy the scopes present in the token._
      
      ##  Use of Scopes
      - Scopes are specified  in each individual API.
      - Depending on the API, scope can be :
        - Mandatory (designed with comment "#Required"): if this scope is not used during the request an error will be returned. An API can have multiple mandatory scopes.
        - Optional scopes will return an optional part of the API.
      
      ## Hierarchical Scopes
      Since API resources are hierarchical, scope follow also this strategy.     
      **Scopes used to request access to resources for OAuth2 security scheme fall into four categories:**

      #### _1. <u>IoT data scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|
      |data:telemetry| Read full telemetry data|
      |data:position| Read vehicle  Location (position) data|
      |data:trip| Read trip related data|
      |data:alert| Read alert related data|
      |data:collision| Read collision related data|
      |data:vehicle:devices:pnc| Read vehicle Plug and Charge related data|

      #### _2. <u>Vehicle remotes scopes:</u>_
      |<b>Scope</b>  |<b>Description</b>  | 
      |---|---|
      |remote:door:write| Read & send door remote (pending & history)|      
      |remote:preconditioning:write| Read & send door Lock remote (pending & history)| 
      |remote:horn:write| Read & send horn remote  (pending & history)| 
      |remote:charging:write| Read & send charging remote (pending & history)| 
      |remote:lights:write| Read & send lights remote (pending & history)| 
      |remote:wakeup:write| Read & send weackup remote (pending & history)| 
      |remote:navigation:write| Read & send navigation remote (pending & history)| 

    ---
    
    # Paging:
    
    To make this necessary feature easy to use when retrieving a collection of results, this API uses a token (computed and interpreted by the backend only) as a context that contains all necessary information allowing the navigation through pages. 
      Token acts as an ```HTTP COOKIE``` on the client-side, so the server does not keep any cache or session settings to continue paging and keep all request stateless.
          
    ---
    
    # Errors:
      Error codes returned by all APIs comply with the standard. Nevertheless, PSA Services (callers) need to have more detailed data structures (even when the answer is not Http-OK) to better categorize the type of error by providing application code, message and debugging code (for investigation purposes). The HTTP code of the response is managed by the protocol itself (in the header).
        
      ### These APIS are likely to report the following HTTP code:
      
      | <b>Code</b>  | <b>Description</b>  |  <b>Case</b> |  
      |---|---|---|
      | 200  |<i>The request has succeeded and the resource data has been sent.</i>|GET APIs.  |
      | 202  |<i>The request has been accepted for processing, but not yet acted upon. An id of processing is returned.</i>|POST/PUT requests:<br>-Create monitor<br>-Create a callbak.| 
      | 204  |<i>The request has been accepted and there is no additional content</i>|DELTE APIs:<br>-Delete monitor.<br>-Delete a callback.|
      |400|<i>Request cannot be processed due to invalid query parameter value of body content (for POST/PUT verbs)</i>|ALL APIs.|
      |401|<i>Unauthorized request due to lack of valid authentication credentials.</i>|All APIs.|
      |403|<i>Unauthorized request due to insufficient credentials to grant access.</i>|All APIs.|
      |404|<i>Target resource not found.|All APIs. Even POST, PUT or DELETE if the resource id is uncknown.</i>|
      |500|<i>Unexpected condition that prevented from fulfilling the reques.</i>|All APIs.|


      
      **Errors are  returned as a generic error response:** see ```ErrorCodeDefaultResponse``` model.
       
    ---
    
    # API Usage:
     
      ## Data output format
      
      **All APIs return data in JSON format. The application who uses them must take into account the evolving character of them and more precisely regarding the schemas of the exposed data. Indeed:**
      
      *  The missing of known data fields should not cause an error. 
      *  It should (correctly)  deal with JSON content with unknown properties also. Indeed, data schema extensions should be supported without errors even if they are not used. 
        
      
      **For example:**
      
      Assuming a given exposed resource with this data schema:
        
          
           data:
            type: object
            description: Data model
            properties:
              field1:
                type: string
              field2:
                type: number
             
      The application should be able to deal with those possible valid JSON contents:
        
      > All fields:
        ```{
          "field1":"value1",
          "field2": 1
        }```
        
      > Missing field2:
        ```{
          "field1":"value1"
        }```        

      > Unknow  field3:
        ```{
          "field1":"value1",
          "field3": 2.5
        }```
      
      ## Callback, Monitor & Remote management:
      - Creation on monitor, remote & subscribe (callback) will be associated to a client ID, user (and vehicle depending on the API requested), therefore:
        - Read operation will only return information previously created by this client ID, user and vehicle association
        - Update, delete operation will only be possible for ressource previously created by this client ID, user and vehicle association
      - A maximum of 5 monitors can be associated to a vehicle, client ID, user. 
    --- 
    
    
    
  
tags:
  - name: User
  - name: Vehicles
    description: Access to Vehicles details.
  - name: Trips
    description: Describe Trips of a a User or Vehicle
  - name: Subscribe
    description: Describe User subscription (callback) to use with remote and/or monitor feature.
  - name: Monitors
    description: Describe the vehicle monitor features.
  - name: Remote
    description: Describe the vehicle monitor features.



paths:
  '/user':
    get:
      tags:
        - User
      summary: User's information
      description: Returns the User's information.
      operationId: getUser
      parameters:
        - $ref: '#/components/parameters/country'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: User not found
          $ref: '#/x-fragment/general_error_fragment'
  '/user/vehicles':
    get:
      tags:
        - Vehicles
      summary: List of vehicles
      description: |
        Returns the Vehicles associated with the User.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:vehicle:devices:pnc|Optional|
      operationId: getVehiclesByDevice
      parameters:
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/pageToken'
        - $ref: '#/components/parameters/vehicleExtension'
        - $ref: '#/components/parameters/vinPrefix'
        - $ref: '#/components/parameters/country'

      security:
        - api_oauth:
          - data:vehicle:devices:pnc

      responses:
        '200':
          description: OK
          content:
            'application/hal+json ':
              schema:
                $ref: '#/components/schemas/Vehicles'
        default:
          description: Vehicle not found
          $ref: '#/x-fragment/general_error_fragment'
          
  '/user/vehicles/{id}':
    get:
      tags:
        - Vehicles
      summary: Details of a vehicle
      description: |
        Returns detailed information about a Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:vehicle:devices:pnc|Optional|
      operationId: getVehicleByid
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/locale'
        - $ref: '#/components/parameters/vehicleExtension'
        - $ref: '#/components/parameters/country'
      security:
        - api_oauth:
          - data:vehicle:devices:pnc

      responses:
        '200':
          description: OK
          content:
            'application/hal+json ':
              schema:
                $ref: '#/components/schemas/Vehicle'
        default:
          description: Vehicle not found
          $ref: '#/x-fragment/general_error_fragment'
          
  '/user/vehicles/{id}/telemetry':
    get:
      summary: Vehicle telemetries.
      tags:
        - Vehicles
      description: |
        Returns the latest Telemetry messages that occurred during a selective timestamp-ranges and bounded by an index range.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
      operationId: getTelemetry
      deprecated : true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/telemetryType'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSizeHighFrequency'
        - $ref: '#/components/parameters/pageToken'
        - $ref: '#/components/parameters/telemetryExtension'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/TelemetrySuccessResponse'
        default:
          $ref: '#/components/responses/TelemetryFailedResponse'
  '/user/vehicles/{id}/lastPosition':
    get:
      tags:
        - Vehicles
      summary: Last position identified
      description: |
        Returns the latest GPS Position of the Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:position|Required|
      operationId: getCarLastPosition
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
      security:
        - api_oauth:
            - data:position #Required
      responses:
        '200':
          description: Position response
          content:
            application/vnd.geo+json:
              schema:
                $ref: '#/components/schemas/Position'
        default:
          description: Vehicle not found
          $ref: '#/x-fragment/general_error_fragment'
 
  '/user/vehicles/{id}/collisions':
    get:
      summary: Collistions occured on the vehicle.
      tags:
        - Vehicles
      description: |
        Returns the list of Collisions that occurred for a given vehicle (id) during the timestamp ranges and bounded by an index range
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:collision|Required|
      operationId: getVehicleCollision
      deprecated: true
      parameters:
        
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:collision #Required
      responses:
        '200':
          $ref: '#/components/responses/CollisionsSuccessResponse'
        default:
          $ref: '#/components/responses/CollisionFailedResponse'
  '/user/vehicles/{id}/collisions/{cid}':
    get:
      summary: A collistion occured on the vehicle.
      tags:
        - Vehicles
      description: |
        Returns the Collision that matches the vehicle id and the Collision cid.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:collision|Required|
      operationId: getVehicleCollisionById
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/collisionId'
      security:
        - api_oauth:
            - data:collision #Required
      responses:
        '200':
          $ref: '#/components/responses/CollisionsuccessResponse'
        default:
          $ref: '#/components/responses/CollisionFailedResponse'
  '/user/vehicles/{id}/maintenance':
    get:
      tags:
        - Vehicles
      description: |
        Returns the latest Maintenance information for a Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Required|
      operationId: getVehicleMaintenance
      parameters:
        - $ref: '#/components/parameters/vehicleId'
      security:
        - api_oauth:
            - data:telemetry #Required
      responses:
        '200':
          description: Maintenant response
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Maintenance'
        default: 
          $ref: '#/x-fragment/general_error_fragment'
          
  '/user/vehicles/{id}/status':
    get:
      tags:
        - Vehicles
      description: |
        Returns the latest vehicle status.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
      summary: Vehicle status.
      operationId: getVehicleStatus
      parameters:
        - $ref: '#/components/parameters/vehicleId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
      responses:
        '200':
          description: Status response
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Status'
        default:
          $ref: '#/x-fragment/general_error_fragment'          
          
  '/user/vehicles/{id}/alerts':
    get:
      tags:
        - Vehicles
      description: |
        Returns the latest alert messages for a Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:alert|Required|
        |data:position|Optional|
      summary: Alerts related to a vehicle.
      operationId: getVehicleAlerts
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:alert #Required
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/AlertsuccessResponses'
        default:
          $ref: '#/components/responses/AlertFailedResponse'
  '/user/vehicles/{id}/alerts/{aid}':
    get:
      tags:
        - Vehicles
      summary : An alert related to a vehicle.
      description: |
        Returns information about a specific alert messages for a Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:alert|Required|
        |data:position|Optional|
      operationId: getVehicleAlertsById
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/alertId'
      security:
        - api_oauth:
            - data:alert #Required
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/AlertsucessResponse'
        default:
          $ref: '#/components/responses/AlertFailedResponse'
          
  '/user/vehicles/{id}/alarms':
    get:
      tags:
        - Vehicles
      description: | 
        Returns a (filtered) list of alarm for a Vehicle.
        *Note:* Timestamp filtering concerns the creation date for status or trigger. 
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Required|
      summary: Vehicle's Alarms
      operationId: getVehicleAlarms
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/alarmType'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:telemetry	#Required
      responses:
        '200':
          $ref: '#/components/responses/AlarmSuccessResponses'
        default:
          $ref: '#/components/responses/AlarmFailedResponse'
  '/user/vehicles/{id}/alarms/{aid}':
    get:
      tags:
        - Vehicles
      description: |
        Returns information about a specific alarm for a Vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Required|
      summary: Vehicle's Alarm
      operationId: getVehicleAlarmsById
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/alarmId'
      security:
        - api_oauth:
            - data:telemetry	#Required
      responses:
        '200':
          $ref: '#/components/responses/AlarmSucessResponse'
        default:
          $ref: '#/components/responses/AlarmFailedResponse'

 
  '/user/vehicles/{id}/trips':
    $ref: '#/x-fragment/Vehicle_id_Trips'
  '/user/vehicles/{id}/trips/{tid}':
    $ref: '#/x-fragment/Vehicle_id_Trip_id'
  '/user/vehicles/{id}/trips/{tid}/alerts':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_Alerts_getter'
  '/user/vehicles/{id}/trips/{tid}/alerts/{aid}':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_Alerts_id_getter'
  '/user/vehicles/{id}/trips/{tid}/collisions':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_Collisions_getter'
  '/user/vehicles/{id}/trips/{tid}/collisions/{cid}':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_Collisions_id_getter'
  '/user/vehicles/{id}/trips/{tid}/wayPoints':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_wayPoints_getter'
  '/user/vehicles/{id}/trips/{tid}/telemetry':
    $ref: '#/x-fragment/Vehicle_id_Trip_id_Telemetry_getter'

          
  '/user/vehicles/{id}/callbacks/{cbid}/monitors':
    get:
      tags:
        - Monitors
      summary: Get all monitors of the vehicle.
      description: |
        Returns the list of subscribed Monitors of the vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
      operationId: getVehicleMonitors
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision     
      responses:
        200:
          $ref: '#/components/responses/MonitorsuccessResponses'
        default:
          $ref: '#/components/responses/MonitorFailedResponse'
    post:
      tags:
        - Monitors
      summary: Create a new Monitor.
      description: |
                    Create a monitor dedicated to a vehicle. It will generates an event following the transition state of one of the (monitored) data  of the vehicles. As for example the fuel level, the moving out of a defined geographical area. 
                    
                    When the trigger occurs, the built event expressed as a JSON object will be sent over the subscribed callback.
                    
                    |Scope Name |Mandatory State|
                    |--------|:---------:|
                    |data:telemetry|Optional|
                    |data:position|Optional|
                    |data:trip|Optional|
                    |data:alert|Optional|
                    |data:collision|Optional|
      operationId: createVehicleVehicleMonitor
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision       
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/MonitorParameter'
                #DataMonitorParm
      responses: 
        202:
          $ref: '#/components/responses/MonitorsuccessPostResponse'
        default:
          $ref: '#/components/responses/MonitorFailedResponse'
          
  '/user/vehicles/{id}/callbacks/{cbid}/monitors/{mid}':
    put:
      tags:
        - Monitors
      summary: Update an existing Monitor.
      description: |
                    Update an existing ```Monitor``` that has been posted (and accepted previously) for this vehicle. The monitor object (body) provided should be complete (the aggregation is not supported for the update of the ```monitor```). 
                    You can first retrieve this object using the ```GET /monitor/{mid}``` API, then modify it and finally publish it (via this ```PUT API```).
                    
                    |Scope Name |Mandatory State|
                    |--------|:---------:|
                    |data:telemetry|Optional|
                    |data:position|Optional|
                    |data:trip|Optional|
                    |data:alert|Optional|
                    |data:collision|Optional|
      operationId: updateVehicleVehicleMonitor
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
        - $ref: '#/components/parameters/monitorId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision       
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/MonitorParameter'
      responses: 
        202:
          $ref: '#/components/responses/MonitorsuccessPostResponse'
        default:
          $ref: '#/components/responses/MonitorFailedResponse'
    get:
      tags:
        - Monitors
      description: |
        Returns information about a specific Monitor for a given vehicle.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
      summary: Get the monitor by monitor Id.
      operationId: getVehicleMonitorsStatusById
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
        - $ref: '#/components/parameters/monitorId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision        
      responses:
        200:
          $ref: '#/components/responses/MonitorsuccessResponse'
        default:
          $ref: '#/components/responses/MonitorFailedResponse'
    delete:
      tags:
        - Monitors
      summary: Delete an existing Monitor.
      description: |
        Stop (disable) an existing Monitor.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
      operationId: deleteVehicleMonitor
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
        - $ref: '#/components/parameters/monitorId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision      
      responses:
        204:
          description: Monitor deleted (the response does not include an entity).
        '400':
          description: Invalid ID supplied
        '404':
          description: Monitor not found
 
  '/user/vehicles/{id}/callbacks/{cbid}/monitors/{mid}/status': 
    put:
      tags:
        - Monitors
      summary: Set a new monitor status.
      description: |
        Set monitor status. 
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
      operationId: setVehicleVehicleMonitorStatus
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/callbackId'
        - $ref: '#/components/parameters/monitorId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision       
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/MonitorStatusSetter'
      responses: #MonitorId
        202:
          $ref: '#/components/responses/MonitorsuccessPostResponse'
        default:
          $ref: '#/components/responses/MonitorFailedResponse'
  
  
  '/user/callbacks':  
    get:
      tags:
        - Subscribe
      summary: Get all callbacks of the user.
      description: |
        Returns the list of subscribed callback of the user.
        |Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
        |remote:door:write|Optional|
        |remote:preconditioning:write|Optional|
        |remote:horn:write|Optional|
        |remote:charging:write|Optional|
        |remote:lights:write|Optional|
        |remote:wakeup:write|Optional|
        |remote:navigation:write|Optional|
      operationId: getUsertRemotes
      parameters:
          - $ref: '#/components/parameters/callbackType'
          - $ref: '#/components/parameters/indexRange'
          - $ref: '#/components/parameters/pageSize'
          - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write
      responses:
        200:
          $ref: '#/components/responses/CallbackSuccessResponses' 
        default:
          $ref: '#/components/responses/CallbackFailedResponse'
    #callbackId      
    post:
        tags:
          - Subscribe
        summary: Register a new reusable callback.
        description: |
          Create a new reusable callback.
          Scope Name |Mandatory State|
          |--------|:---------:|
          |data:telemetry|Optional|
          |data:position|Optional|
          |data:trip|Optional|
          |data:alert|Optional|
          |data:collision|Optional|
          |remote:door:write|Optional|
          |remote:preconditioning:write|Optional|
          |remote:horn:write|Optional|
          |remote:charging:write|Optional|
          |remote:lights:write|Optional|
          |remote:wakeup:write|Optional|
          |remote:navigation:write|Optional|
        operationId: setUsertVehicleRemote
        security:
          - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write
        requestBody:
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/CallbackSubscribe'
        responses: #MonitorId
          200:
            $ref: '#/components/responses/CallbackSuccessPostResponse'
          default:
            $ref: '#/components/responses/CallbackFailedResponse'      
            
  '/user/callbacks/{cbid}':
    put:
        tags:
          - Subscribe
        summary: Update an existing  callback.
        description: |
          Update an existing ```Callback``` that has been posted (and accepted previously) for the user. The callback object (body) provided should be complete (aggregation is not supported for the update). This object can be retrieved  using the ```GET /user/remote/callbacks/{cbid}``` API then modify it and finally publish it (via this ```PUT API```) 
          Scope Name |Mandatory State|
          |--------|:---------:|
          |data:telemetry|Optional|
          |data:position|Optional|
          |data:trip|Optional|
          |data:alert|Optional|
          |data:collision|Optional|
          |remote:door:write|Optional|
          |remote:preconditioning:write|Optional|
          |remote:horn:write|Optional|
          |remote:charging:write|Optional|
          |remote:lights:write|Optional|
          |remote:wakeup:write|Optional|
          |remote:navigation:write|Optional|
        operationId: setUsertVehicleRemoteById
        parameters:
          - $ref: '#/components/parameters/callbackId'
        security:
          - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write       
        requestBody:
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/CallbackSubscribe'
        responses: #MonitorId
          202:
            $ref: '#/components/responses/CallbackSuccessPostResponse'
          default:
            $ref: '#/components/responses/CallbackFailedResponse'
    get:
      tags:
        - Subscribe
      summary: Get a user callback.
      description: |
        Returns a subscribed callback of the user by subscribe ID.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
        |remote:door:write|Optional|
        |remote:preconditioning:write|Optional|
        |remote:horn:write|Optional|
        |remote:charging:write|Optional|
        |remote:lights:write|Optional|
        |remote:wakeup:write|Optional|
        |remote:navigation:write|Optional|
      operationId: getUsertRemotebyId
      parameters:
          - $ref: '#/components/parameters/callbackId'
      security:
        - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write 
      responses:
        200:
          $ref: '#/components/responses/CallbackSuccessResponse' 
        default:
          $ref: '#/components/responses/CallbackFailedResponse'
    delete:
      tags:
        - Subscribe
      summary: Delete an existing callback.
      description: |
                  Delete an existing callback.
                    * Notes: 
                      * If there was an ongoing Remote-Operation then its status  will never be delivered.
                      * Deleting the callback will also delete all of its associated monitors.
                  Scope Name |Mandatory State|
                  |--------|:---------:|
                  |data:telemetry|Optional|
                  |data:position|Optional|
                  |data:trip|Optional|
                  |data:alert|Optional|
                  |data:collision|Optional|
                  |remote:door:write|Optional|
                  |remote:preconditioning:write|Optional|
                  |remote:horn:write|Optional|
                  |remote:charging:write|Optional|
                  |remote:lights:write|Optional|
                  |remote:wakeup:write|Optional|
                  |remote:navigation:write|Optional|
      operationId: deleteUsertRemote
      parameters:
        - $ref: '#/components/parameters/callbackId'
      security:
          - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write 
      responses:
        204:
          description: Callback deleted (the response does not include an entity)
        '400':
          description: Invalid ID supplied
        '404':
          description: Callback not found
  
  '/user/callbacks/{cbid}/status': 
    put:
      tags:
        - Subscribe
      summary: Set an existing callback new status.
      description: |
        Set the user callback status.```Paused``` means that the callback will not post any event.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:telemetry|Optional|
        |data:position|Optional|
        |data:trip|Optional|
        |data:alert|Optional|
        |data:collision|Optional|
        |remote:door:write|Optional|
        |remote:preconditioning:write|Optional|
        |remote:horn:write|Optional|
        |remote:charging:write|Optional|
        |remote:lights:write|Optional|
        |remote:wakeup:write|Optional|
        |remote:navigation:write|Optional|
      operationId: setUserCallbackStatus
      parameters:
        - $ref: '#/components/parameters/callbackId'
      security:
          - api_oauth:
            - data:telemetry
            - data:position
            - data:trip
            - data:alert
            - data:collision
            - remote:door:write
            - remote:preconditioning:write
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write    
      requestBody:
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/CallbacksStatusSetter'
      responses: 
        202:
          $ref: '#/components/responses/CallbackSuccessPostResponse'
        default:
          $ref: '#/components/responses/CallbackFailedResponse'

          
  '/user/vehicles/{id}/callbacks/{cbid}/remotes':
    post:
      tags:
        - Remote
      summary: Send a remote action to a vehicle.
      description: |
                      Create a new asynchrone vehicle remote action and request it.
                      The REMOTE action is specified by the Remote object which offers a set of possible actions (preconditioning, door, horn, charging, lights, wakeup, navigation).
                       
                       However, each remote action needs a different permissions set.
                        This API has therefore defined a set of SCOPE OAUTH2 to cover all possible actions. But the user   should only have the SCOPEs necessary for the action his is requesting for. The necessary scopes  for each action are defined as follows:
                        
                      | <b>Remote action</b>  | <b>Scope</b>  |  <b>Mandatory</b>  | 
                      |---|---|---|
                      |preconditioning| remote_preconditioning_write|Optional|
                      |door - lock & unlock action| remote_door_lock_write|Optional|
                      |horn| remote_horn_write|Optional|
                      |charging| remote_charging_write|Optional|
                      |lights| remote_lights_write|Optional|
                      |wakeup| remote_wakeup_write|Optional|
                      |navigation| remote_navigation_write|Optional|                    
                        
                        
                       The backend server will introspect the OAuth2 provided token and check if it contains the necessary scope authorization to perform the requested remote action. or raise an unauthorized error status.
      operationId: sendRemoteToVhl
      parameters:
          - $ref: '#/components/parameters/vehicleId'
          - $ref: '#/components/parameters/callbackId'
      security:
        - api_oauth: 
            - remote:door:write
            - remote:preconditioning:write	
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write
      requestBody:
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Remote'
      responses: #MonitorId
          202:
            $ref: '#/components/responses/RemoteActionsSuccessPostResponse'
          default:
            $ref: '#/components/responses/CallbackFailedResponse'
  
    get:
      tags:
        - Remote
      summary: Get all remote action of vehicle and callback.
      description: |
        Returns the list of action remote requested for vehicle.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |remote:door:write|Optional|
        |remote:preconditioning:write|Optional|
        |remote:horn:write|Optional|
        |remote:charging:write|Optional|
        |remote:lights:write|Optional|
        |remote:wakeup:write|Optional|
        |remote:navigation:write|Optional|
      operationId: getRemoteRequestsForVhl
      parameters:
          - $ref: '#/components/parameters/vehicleId'
          - $ref: '#/components/parameters/callbackId'
          - $ref: '#/components/parameters/indexRange'
          - $ref: '#/components/parameters/pageSize'
          - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - remote:door:write
            - remote:preconditioning:write	
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write         
      responses:
        200:
          $ref: '#/components/responses/RemoteActionSuccessResponses' 
        default:
          $ref: '#/components/responses/CallbackFailedResponse'
          
  '/user/vehicles/{id}/callbacks/{cbid}/remotes/{rid}':
    get:
      tags:
        - Remote
      summary: Get remote action by id.
      description: |
        Returns the remote action requested for vehicle by ID.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |remote:door:write|Optional|
        |remote:preconditioning:write|Optional|
        |remote:horn:write|Optional|
        |remote:charging:write|Optional|
        |remote:lights:write|Optional|
        |remote:wakeup:write|Optional|
        |remote:navigation:write|Optional|
      operationId: getRemoteRequestForVhlById
      parameters:
          - $ref: '#/components/parameters/vehicleId'
          - $ref: '#/components/parameters/callbackId'
          - $ref: '#/components/parameters/remoteId'
      security:
        - api_oauth:
            - remote:door:write
            - remote:preconditioning:write	
            - remote:horn:write
            - remote:charging:write
            - remote:lights:write
            - remote:wakeup:write
            - remote:navigation:write         
      responses:
        200:
          $ref: '#/components/responses/RemoteActionSuccessResponse' 
        default:
          $ref: '#/components/responses/CallbackFailedResponse'
          
    # RemoteActionSuccessResponse
components:
  securitySchemes:
    api_keyAuth:        
      type: apiKey
      in: query      
      name: client_id  # name of the header, query parameter or cookie
    api_oauth:
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
      flows:
        implicit:
          authorizationUrl: 'https://api.mpsa.com/api/connectedcar/v2/oauth/authorize'
          scopes:
            data:telemetry:	Read full telemetry data
            data:position:	Read vehicle Location (position) data
            data:trip:	Read trip related data
            data:alert:	Read alert related data
            data:collision:	Read collision related data
            remote:door:write:	Read & send door remote (pending & history)
            remote:preconditioning:write:	Read & send door Lock remote (pending & history)
            remote:horn:write:	Read & send horn remote (pending & history)
            remote:charging:write:	Read & send charging remote (pending & history)
            remote:lights:write:	Read & send lights remote (pending & history)
            remote:wakeup:write:	Read & send weackup remote (pending & history)
            remote:navigation:write:	Read & send navigation remote (pending & history)         

  schemas:
    Tab_Links:
      description: >
        [HAL](https://en.wikipedia.org/wiki/Hypertext_Application_Language#Convention)
        (Hypertext Application Language) link collection
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        first:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
        prev:
          $ref: '#/components/schemas/Link'
        last:
          $ref: '#/components/schemas/Link'
      required : [self, first]
   
    CollectionResult:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/Tab_Links'
        total:
          type: integer
        totalPage:
          type: integer
        currentPage:
          type: integer
        _embedded:
          type: object
      required: [total, totalPage, currentPage, _embedded, _links]
        
   
    Alert:
      allOf: 
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/UpdatedAtField' 
        - title: Alert message
          type: object
          properties:
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/Link'
                vehicle:
                  $ref: '#/components/schemas/Link'
                position:
                  $ref: '#/components/schemas/Link'
                trips:
                  type: array
                  items: 
                    $ref: '#/components/schemas/Link'
              required : [self]
            id:
              type: string
              example : 0a9de72cc3803b12a74418acd20dcd66634fa82e44b2ec7060bca91462dc5772199559905caefe168812918d47f67253f33d477b645bb59afdd1268b81e382999
            active:
              type: boolean
              example : true
            type:
              $ref: '#/components/schemas/AlertMsgEnum'
            severity:
              description: |
                            Alert severity level.
                            
                            |Severity|Description|
                            |:---|:---|
                            |Information|Better to fix but it is operating accurately.|
                            |Warning|Should fix it asap.|
                            |Critical|Starting prohibited without repair.|                          
              type: string
              enum: [Information, Warning, Critical]
              example : Information
            startedAt:
              type: string
              format: date-time
            endAt:
              type: string
              format: date-time
            startPosition:
              allOf:
                - $ref: '#/components/schemas/Position'
                - description: The position (last vehicle known one) where the alert appears.
            endPosition:
              allOf:
                - $ref: '#/components/schemas/Position'
                - description: The position (last vehicle known one) where the alert disappears. 
          required: [ id,active,type,updatedAt,startedAt,_links]
          
  
    Url:
      type: string
      description:  URL format follows [RFC 3986](https://tools.ietf.org/html/rfc3986) and
        usually looks like this ` scheme://host[:port][/Path] `
    Link:
      type: object
      description: A Link Object as defined by [JSONHAL#Link
        Object](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5).
      required:
        - href
      properties:
        href:
          $ref: '#/components/schemas/Url'
        templated:
          type: boolean
          description: SHOULD be true when the Link Object's "href"   property is a URI
            Template
        type:
          type: string
          description: a hint to indicate the media type  expected when dereferencing the
            target resource.
        deprecation:
          allOf:
            - $ref: '#/components/schemas/Url'
            - description:  indicates that the link is to be deprecated (i.e. removed) at a
                future date.  Its value is a URL that SHOULD provide further
                information about the deprecation.
        name:
          type: string
        title:
          type: string
          description: Its value is a string and is intended for labelling the link with a
            human-readable identifier (as defined by
            [RFC5988](https://tools.ietf.org/html/rfc5988)).
        profile:
          type: string
          description: Its value is a string and is intended for indicating the language of
            the target resource (as defined by [RFC5988]).
        hreflang:
          type: string
          description: Its value is a string which is a URI that hints about the profile
            (as defined by
            [I-D.wilde-profile-link](https://tools.ietf.org/html/draft-kelly-json-hal-08#ref-I-D.wilde-profile-link))
            of the target resource.
   
    CollisionDetails:
        type : object
        properties:
          side:
            type: string
            description: Indicates the side of the collision
            enum: [Front, Rear, Lateral]
            example : Lateral
          severity:
            type: string
            enum: [Minimal, Minor, Major]
            example : Minor
            description: >-
                * Minimal stands for no emergency system activated during the collision.
                
                * Minor only pretensioner system activated.
                
                * Major for airbag and prentensioner activation.
        required : 
          - side
    CollisionObj:
     allOf:
        - title: Collision
          type: object
          properties:
            details:
                type : array
                items : 
                  $ref: '#/components/schemas/CollisionDetails'
    
    Collision:
     allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/CollisionObj'
        - title: Collision
          type: object
          properties:
            id:
              type: string
              example : 055d8f0a0089d7b9226989ce2db42511e2e19df8cc106a7fb7d0c7fb92ab2320c0720e94be1ee517b3172da70dd05446a934cccca524172d9add54d8dbce51b14
            tippedOver:
              type: boolean
              description: >-
                    Indicates if the car tipped over during the collision.
                    Warning : This information is applicable only on vehicles equipped with dedicated sensor and is optionnal
            pedestrian:
              type: boolean
              description: >-
                    Indicates if the collision involve a pedestrian.
                    Warning : This information is applicable only on vehicles equipped with dedicated sensor and is optionnal
            updatedAt:
              type: string
              format: date-time
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/Link'
                vehicle:
                  $ref: '#/components/schemas/Link'
                trip:
                  $ref: '#/components/schemas/Link'
              required : [self]
          required: [ id, _links, createdAt ]
          
    ECoaching:
      title: ECoaching response
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            vehicle:
              $ref: '#/components/schemas/link'
            trip:
              $ref: '#/components/schemas/link'
       
        scores:
          type: array
          items:
              type: object
              properties:
                category:
                  type: string
                  description: category of the score. Global, ACCELERATION, BREAKING, A/C system, Runing cold engine, Direct Shift Gear, Speed, STT system, ZEV (Zero emission vehicle).
                  enum: [Global, Acceleration, Break, AirCondioner, ColdEngine, TirePressure, Slope, Speed, StartStop]
                  example : ColdEngine
                score:
                  type: number
                  minimum: 0
                  example : 6
                  maximum: 10
       
        _embedded:
          type: object
    
    EngineLiquid:
      type: object
      properties:
        level:
          description: Engine liquid level expressed in persent.
          type: integer
          minimum : 0
          maximum : 100
        temp:
          description: Engine liquid temperature expressed in Celsius degrees.
          type: number
          format: float      
    EngineAir:
      type: object
      properties:
        temp:
          description: Engine air temperature expressed in Celsius degrees.
          type: number
          format: float
          
    Engines:
      type: array
      items: 
         $ref: '#/components/schemas/Engine'
    PowertrainBase:
      type: object
      properties:
        status : 
          type : string
          description : Status of the powertrain
          enum: [NotRunning, Starting, Running, Stopping, Stopped]
    Powertrain :
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/PowertrainBase'
      required: [createdAt]
    EngineBase:
          type: object
          properties:
                  type:
                          type: string
                          default: Thermic
                          enum:
                            - Thermic
                            - Electric
                          example : Thermic
                  oil:
                    type: object 
                    deprecated: true
                    description: depricated, use extention thermic for such purpose.
                    properties:
                      temp:
                        type: number
                        format: float
                        example : 33,3
                  speed:
                    type: number
                    format: float
                  gmpStatus:
                    type: string
                    enum: [NotRunning, Starting, Running, Stopping, Stopped]
                    example : Running
                    deprecated : true
                  extension:
                    type: object
                    properties:
                        thermic:
                          type: object
                          properties:
                            coolant:
                              allOf:
                                - description: Engine coolant liquid properties.
                                - $ref: '#/components/schemas/EngineLiquid'
                            oil:
                              allOf:
                                - description: Engine oil properties.
                                - $ref: '#/components/schemas/EngineLiquid'
                            air:
                              allOf:
                               - $ref: '#/components/schemas/EngineAir'

    Engine:
        allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - $ref: '#/components/schemas/EngineBase'
        required : [createdAt]
        

    MaintenanceObj:
     allOf:
        - $ref: '#/components/schemas/UpdatedAtField'
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/MaintenanceBase'
    
    MaintenanceBase:
      type : object
      description: Expresses next Maintenance details. Such as number of days and the mileage until the next Maintenance. The value is negative if the next maintenance (day or mileage) is already passed. At least one of the following maintenance information will be provided.
      title: Maintenance
      properties:
        daysBeforeMaintenance:
          type: integer
          example : 45
        mileageBeforeMaintenance:
          type: number
          format : float
          example : 1239,6
      required: [createdAt]
              
    Maintenance:
      allOf:
          - $ref: '#/components/schemas/MaintenanceObj'
          - title: Maintenance response
            properties:
              _links:
                type: object
                properties:
                  self:
                    $ref: '#/components/schemas/Link'
                  vehicle:
                    $ref: '#/components/schemas/Link'
                  alerts:
                    $ref: '#/components/schemas/Link'
                required : [self]
            required:
              - _links
     
    Ignition:
        allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/IgnitionBase'
        
    IgnitionBase:
          type: object
          properties:
            type:
                type: string
                enum: [Stop, StartUp, Start]
                example : Start
          required: [type,createdAt]
  
           
    VehicleOdometer: 
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - type: object
          properties:
            mileage:
                  description: Vehicle mileage expressed in KM.
                  type: number
                  format : float
                  minimum : 0.0
                  example : 12978,9
      required : [ createdAt]
    
    Adas:  
                type: object
                properties:
                  parkAssist:
                    type: object
                    properties:
                      front:
                        type: array
                        items:
                          type: string
                          enum:
                            - Fault
                            - DriverInhibition
                            - Active
                            - Wait
                            - OutOfService
                          example : Active
                      rear:
                        type: array
                        items:
                          type: string
                          enum:
                            - Fault
                            - DriverInhibition
                            - TrailerInhibition
                            - Active
                            - Wait
                            - OutOfService 
                          example : TrailerInhibition
                  accr:
                    description: Adaptive Cruise Control Regulation
                    type: string
                    enum:
                      - Activated
                      - Fault
                      - Hold
                      - HoldWithOverSpeeding
                      - Off
                      - OverSpeedingByPedalPress
                      - StandBy
                    example : HoldWithOverSpeeding
                  lvv:
                    type: boolean
                    example : true
                  rvv:
                    type: string
                    enum:
                      - Off
                      - NoBestFit
                      - BestFitInProgress
                      - BestFitMax
                      - BestFitMin
                      - BestFitDeactivated
                      - AutoDeactivated
                      - OverflowSpeedConsign
                      - LackOfVisibilityRadar
                      - LearningRadar
                      - Deactivated
                      - LimitSetting
                    example : AutoDeactivated
                  aebs:
                    description: Advanced Emergency Braking System
                    type: string
                    enum:
                      - off
                      - Fixed
                      - OnFlashing
                    example : Fixed
                  afil:
                    description: Lane Departure Warning System
                    type: string
                    enum: [FlashingFault, FlashingWarning, Off, OnFixed]
                    example : FlashingWarning
                  artiv:
                    description: Respect of inter vehicle time assist (ARTIV)
                    type: string
                    enum:
                      - NotSelected
                      - Selected
                      - Unavailable
                    default: Unavailable
                    example : Selected
                  bsm:
                    description: Blind Spot Monitoring
                    type: string
                    enum:
                      - Active
                      - Inactive
                      - Disabled
                      - Fault
                    example : Active
                  esp:
                    description: Electronic Stability Program
                    type: boolean
                    example : true
                  abs:
                    description: Anti-lock braking system
                    type: boolean
                    example : false
                  fse:
                    description: Electric brake service
                    type: boolean
                    example : true
                  sli:
                    description: Speed Limit Information (expressed in km/h)
                    type: integer
                    example : 110
                  rlka:
                    description: Right Lane Keeping Assist 
                    type: string
                    enum: [Authorized, CorrectionInProgress, NotAuthorized, NotSelected]
                    example : Authorized
                  llka:
                    description: Left Lane Keeping Assist 
                    type: string
                    enum: [Authorized, CorrectionInProgress, NotAuthorized, NotSelected]
                    example : CorrectionInProgress
                  rgi:
                    description: Recommended gear indicator
                    type: string
                    enum:
                      - None
                      - Up
                      - Down
                      - UpDown
                    example : None
         
    Lights:
      description: Expresses all light, direction (```Left```, ```Right``` ),  position (```Front```, ```Rear``` ) and status  (```Off```, ```On```) for a category.
      type: array
      items:
        type: object
        properties:
          direction:
            type: string
            enum: [Left, Right]
          position:
            type: string
            enum: [Front, Rear]
          status:
            type: string
            enum: [Off, On]
        
          
    LightingSystemBase:
                description: Expresses the Directional, Fog and the Position vehicle lights.
                type: object
                properties:
                  turn:
                     $ref: '#/components/schemas/Lights' 
                  fog:
                     $ref: '#/components/schemas/Lights'
              
    LightingSystem:
                    allOf:
                      - $ref: '#/components/schemas/CreatedAtField'
                      - $ref: '#/components/schemas/LightingSystemBase'  
                    required: [createdAt]
    
  
    BasicKinetic:
            description: |
                          Everything related to the movement of the vehicle. Speed, acceleration..
            properties:
                acceleration:
                  type: number
                  format: float
                  description:  Vehicle acceleration (expressed in m/s²)
                speed:
                  type: number
                  format: float
                  description:  Vehicle speed (expressed in km/h)
                moving:
                  type: boolean 
    
    Kinetic:
        allOf:
          - $ref: '#/components/schemas/CreatedAtField'
          - $ref: '#/components/schemas/BasicKinetic'
        required : [ createdAt]
    
    DrivingBehavior:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/DrivingBehaviorBase'
      required: [createdAt]

    DrivingBehaviorBase:
      description: Describe the behavior of the driver
      type: object
      properties:
        mode:
          description : Driving mode by driver selection
          type : string
          enum:
              - Normal
              - Sport
              - Comfort
              - Eco
              - Sand
              - Mud
              - Snow
              - ZEV
              - Hybrid
              - ZEVEco
              - HybridEco
              - EcoPlus
              - eAWD
              - 4AWD
              - ReinforcedLoad

    Transmission:
              type: object
              properties:
                gearbox:
                  type: object
                  properties:
                    mode:
                      type: object
                      properties:
                        automatic:
                          type: boolean
                        sport:
                          type: boolean
                        snow:
                          type: boolean
                        sequential:
                          type: boolean
                        semiManual:
                          type : boolean
                    ratio:
                      description: Current gear-box ratio.
                      type: string
                      enum:
                            - Ratio1
                            - Ratio2
                            - Ratio3
                            - Ratio4
                            - Ratio5
                            - Ratio6
                            - Ratio7
                            - Ratio8      
                            - Neutral
                            - Reverse

    Privacy:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/PrivacyBase'
      required : [ createdAt]
    
    PrivacyBase:
      type: object
      properties:
        state:
          type: string
          enum: [None, Geolocation, Full]
  
    Battery:  
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/BatteryBase'
      required : [ createdAt]
              
    BatteryBase:  
                description: Describe the car (with combustion engine)  battery status.
                type: object
                properties:
                  voltage:
                    type: number
                    description: Auxiliary battery (12V) state of health in %
                    format: float
  

    Safety:  
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/BaseSafety'
      required : [ createdAt]
          
    BaseSafety:  
      type: object
      properties:
        beltStatus:
          type: array
          items:
            $ref: '#/components/schemas/BeltStatus'
        autoECallTriggering:
          type: string
          enum: [NotDetected, Detected, ShockDetectionUnabled]
          
    ServiceType:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - type: object
        - properties:
            type:
              type: string
              enum: [Electric, Hybrid, Unknown]
          required: [createdAt]
          deprecated : true
    BeltStatus:  
      type: object
      description: Seat belt condition.
      properties:
        belt: 
          description: Belt status. 
          type: string
          enum: [Normal, Omission]
        id: 
          description: Seat identifier.
          type: string
          enum: [Driver, Passenger] 
      
    WipingBladesState:  
      type: object
      properties:
        active: 
            description: Either active (true) or not (false).
            type: boolean
        speed:
          description: Wiping speed. This field is present only if active field is set to true.
          type: string
          enum: [High, Low]
  
    DoorsState:
        allOf:
          - $ref: '#/components/schemas/CreatedAtField'
          - type: object
            properties:
                lockedStates:
                  type: array
                  description: List of all known doors' states 
                  items:
                    type: string
                    enum: [Unlocked, Locked, SuperLocked, DriverDoorUnlocked, CabinDoorsUnlocked, CargoDoorsLocked, CargoDoorsUnlocked, RearDoorsUnlocked, RearDoorsLocked, TrunkLocked, TrunkUnLocked] 
                opening:
                  type: array
                  items:
                    type: object
                    description: Opening state per door.
                    properties :
                      identifier: 
                        type: string
                        enum: [Driver, Passenger, RearLeft, RearRight, Trunk, RearWindow, RoofWindow]
                      state:
                        type: string
                        enum: [Open, Closed]
        required : [createdAt]
                        
    DoorsStateBase:
            type: object
            properties:
                lockedStates:
                  type: array
                  description: List of all known doors' states 
                  items:
                    type: string
                    enum: [Unlocked, Locked, SuperLocked, DriverDoorUnlocked, CabinDoorsUnlocked, CargoDoorsLocked, CargoDoorsUnlocked, RearDoorsUnlocked, RearDoorsLocked, TrunkLocked, TrunkUnLocked] 
                opening:
                  type: array
                  items:
                    type: object
                    description: Opening state per door.
                    properties :
                      identifier: 
                        type: string
                        enum: [Driver, Passenger, RearLeft, RearRight, Trunk, RearWindow, RoofWindow]
                      state:
                        type: string
                        enum: [Open, Closed] 
          
    Status:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/UpdatedAtField'
        - title: Vehicle status response
          description: Describe the latest status of the vehicule
          type: object
          properties:
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/link'
                vehicle:
                  $ref: '#/components/schemas/link'
              required : [self]
            ignition:
                  $ref: '#/components/schemas/Ignition'
            lastPosition:
                  $ref: '#/components/schemas/Position'
            preconditioning:
                  $ref: '#/components/schemas/Preconditioning'
            energies:
              type: array
              items:
                  $ref: '#/components/schemas/Energy'
            engines:
                  $ref: '#/components/schemas/Engines'
            powertrain:
                  $ref: '#/components/schemas/Powertrain'
            doorsState:
                  $ref: '#/components/schemas/DoorsState'
            privacy:
                  $ref: '#/components/schemas/Privacy'
            battery:
                  $ref: '#/components/schemas/Battery'
            service:
                  $ref: '#/components/schemas/ServiceType'
            safety:  
                  $ref: '#/components/schemas/Safety'
            odometer: 
                  $ref: '#/components/schemas/VehicleOdometer'
            kinetic :
                  $ref: '#/components/schemas/Kinetic'
            environment: 
                  $ref: '#/components/schemas/Environment'
            drivingBehavior:
                  $ref: '#/components/schemas/DrivingBehavior'
            lightingSystem:
                      $ref: '#/components/schemas/LightingSystem'
            alarm:
                  $ref: '#/components/schemas/VehicleStatusAlarm'
            preconditionning:
              allOf:
                  - $ref: '#/components/schemas/Preconditioning'
                  - deprecated: true
            energy:
              allOf:
                  - $ref: '#/components/schemas/Energy'
                  - deprecated: true                  
          required: [_links, createdAt]
        
    Geometry:
      title: Geometry
      type: object
      description: >-
            This object expresses a GeoJSON Point as specified by
            [rfc7946](https://tools.ietf.org/html/rfc7946#section-3.1.2).
      properties:
        coordinates:
          title: Coordinates
          description: Geometry coordinates
      externalDocs:
        url: 'https://tools.ietf.org/html/rfc7946#section-3.1'
      required:
        - coordinates
        - type
    Point:
      allOf:
        - $ref: '#/components/schemas/Geometry'
        - title: Point
        - description: >-
            This object expresses a GeoJSON Point as specified by
            [rfc7946](https://tools.ietf.org/html/rfc7946#section-3.1.2).
        - properties:
            type:
                type: string
                default: Point
                enum:
                    - Point
            coordinates:
                description: >-
                    This is a simple 2 (or more) numbers vector used to define Geometry
                    Point objects.
                type: array
                items:
                    type: number
                    format: float
                    minItems: 2
        - required: [type,coordinates]
        - example: 
            type: Point
            coordinates:
              - 5.970338 
              - -62.536239
    
    Position:
      allOf:
        - required:
            - geometry
            - properties
            - type
          type: object
          title: Position
          properties:
            type:
              type: string
              default: Feature
              enum:
                - Feature
            geometry:
              $ref: '#/components/schemas/Point'
            properties:
              allOf : 
                - $ref: '#/components/schemas/CreatedAtField' 
                - type: object
                  properties:
                    heading:
                      type: integer
                      description: Course angle expressed in degree. 
                      minimum: 0
                      maximum: 360
                    signalQuality:
                      type: integer
                    type:
                      type: string
                      enum:
                        - Estimated
                        - Acquire
                    fixStatus:
                      type: string
                      description : Fix status information is only returned when position type is set to Acquire. Horizontal & altitude position can be determined in 3D fix status mode where it is only horizontal position in 2D mode. 
                      enum:
                        - 2D
                        - 3D
              required : 
                - createdAt
    
    PositionBase:
      allOf:
        - required:
            - geometry
            - properties
            - type
          type: object
          title: Position
          properties:
            type:
              type: string
              default: Feature
              enum:
                - Feature
            geometry:
              $ref: '#/components/schemas/Point'
            properties:
              allOf : 
                - type: object
                  properties:
                    heading:
                      type: integer
                      description: Course angle expressed in degree. 
                      minimum: 0
                      maximum: 360
                    signalQuality:
                      type: integer
                    type:
                      type: string
                      enum:
                        - Estimated
                        - Acquire
                    fixStatus:
                      type: string
                      description : Fix status information is only returned when position type is set to Acquire. Horizontal & altitude position can be determined in 3D fix status mode where it is only horizontal position in 2D mode.  
                      enum:
                        - 2D
                        - 3D
                  
    LiteEnergy:
      description: Describe vehicle energy supply for thermic, low emission vehicle or both.
      type: object
      properties :
        type:
          $ref: '#/components/schemas/EnergyType'
        subType:
          $ref: '#/components/schemas/EnergySubType'
        level:
          type: number
          format: float
          description: Percentage of remaining energy (Fuel or electric) level. Expressed with a precision of 0.1%.
          minimum: 0
          maximum: 100
        autonomy:
          description: Vehicle autonomy expressed in km for this energy class.
          type: integer
    Energy:
      type: object
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/LiteEnergy'
      properties :
        updatedAt:
          description: Date when the resource has been updated.
          type: string
          format: date-time
          deprecated: true
        extension:
          type: object
          properties:
            fuel:
              description: Specific fuel energy properties.
              type: object
              properties:
                consumption:
                  $ref: '#/components/schemas/FuelEnergyInstantConsumption'
                consumptions:
                  $ref: '#/components/schemas/CompositFuelEnergyConsumption'
            electric:
              description: Specific electric energy parameters.
              type: object
              properties:
                residual:
                   $ref: '#/components/schemas/ElectricResidualEnergy'
                battery:
                  $ref: '#/components/schemas/EnergyBattery'
                charging:
                  $ref: '#/components/schemas/EnergyCharging'
                consumption:
                     $ref: '#/components/schemas/ElectricEnergyInstantConsumption'
      required: [type, createdAt]

    EnergyBase:
      description: Describe vehicle energy supply for thermic, low emission vehicle or both.
      type: object
      properties :
        type:
          type: string
          description: Energy type present on the vehicle.
          enum: [Fuel, Electric]
        subType:
          type: string
          description: | 
            Energy subtype. This field is not mandatory and therefore if it is not present, it means that the resource consumer should only process the primary energy type. The enumeration of the subtypes is not exhaustive and may contain more elements depending on the evolution of the vehicles. The consumer of the data must take this constraint into account. The Fossil and Electric energy subtypes are only used to populate this subtype for the default Fuel and Electric types.
              * Electric and hydrogen type are considered as low emission vehicle whereas fuel(fossil) is associated to thermic energy
          enum: [FossilEnergy, ElectricEnergy, Hydrogen]          
        level:
          type: number
          format: float
          description: Percentage of remaining energy (Fuel or electric) level. Expressed with a precision of 0.1%.
          minimum: 0
          maximum: 100
        autonomy:
          description: Vehicle autonomy expressed in km for this energy class.
          type: integer
          minimum : 0
        extension:
          type: object
          properties:
            fuel:
              description: Specific fuel energy properties.
              type: object
              properties:
                consumption:
                  $ref: '#/components/schemas/FuelEnergyInstantConsumption'
                consumptions:
                  $ref: '#/components/schemas/CompositFuelEnergyConsumption'
            electric:
              description: Specific electric energy parameters.
              type: object
              properties:
                residual:
                   $ref: '#/components/schemas/ElectricResidualEnergy'
                battery:
                  $ref: '#/components/schemas/EnergyBatteryBase'
                charging:
                  $ref: '#/components/schemas/EnergyCharging'
                consumption:
                     $ref: '#/components/schemas/ElectricEnergyInstantConsumption'
      required: [type]


    CompositFuelEnergyConsumption:
              description: Fuel consumption.
              type: object
              properties:
                total:
                  description: Total Fuel consumption expressed in cL.
                  type: number
                  format: float
                  minimum: 0
                instant:
                  description: |
                    Instant Fuel consumption.
                    * If subType equal to FossilEnergy than it will be expressed in L/100Km.
                    * If subType equal to Hydrogen than it will be expressed in Kg/100Km.
                  type: number
                  format: float
    Consumption:
          type: object
          properties:
              consumption:
                type: number
                format: float
                minimum: 0
          required: [consumption]
          deprecated: true

    EnergyConsumption:
        allOf:
              - $ref: '#/components/schemas/Consumption'
              - description: Vehicle total consumption related to a specific type of energy. Expressed in L for fuel energy type or in KWh for eletric one.
              - properties:
                  avgConsumption:
                    description: Vehicle Average consumption per 100kms for specific enery type. For eletric  in terms of Wh/100km or for fuel in terms of cl/100km respectively
                    type: number
                    format: float
                  type:
                    $ref: '#/components/schemas/EnergyType'
                  subType:
                    $ref: '#/components/schemas/EnergySubType'              
              - required: [type]  
                    
    FuelEnergyInstantConsumption:
        allOf:
              - description: Instant consumption for vehicles for fuel energy. Expressed L/100Km
              - $ref: '#/components/schemas/Consumption'
              
    ElectricEnergyInstantConsumption:
         allOf:
              - description: Instant consumption for vehicles for eletric energy. Expressed in KW/H
              - $ref: '#/components/schemas/Consumption'  
           
    ElectricResidualEnergy:
         allOf:
              - description: Residual electric energy (KWh)
              - $ref: '#/components/schemas/Consumption'
                  
    EnergyCharging:
      type: object
      description: Electric battery capacity and heath
      properties:
        plugged:
          type: boolean
        status:
          $ref: '#/components/schemas/ChargingStatusEnum'
        remainingTime:
          description: Remaning time before the battery is fully charged. This duration is expressed using [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) format.
          type: string
        chargingRate:
          description:  Charging speed (expressed in gained batteryLife per hour -> KM/H).
          type: integer
          minimum: 0
          maximum: 500
        chargingPowerLevel:
          description:  Charging power level. Expressed by possible values enum. This enum list may change in the future. The application must be aware of this and provide for lenient deserialization.
          type: string
          enum: [Level1,Level2,Level3,Level4,Level5]
        chargingMode:
            description:  The charging mode; Slow, Quick and No(not charging).
            type: string
            enum: [ No, Slow, Quick ]
        nextDelayedTime:
          description:  Duration (as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)) until the next battery charging.
          type: string
        chargingEndTime:
          type: string                        
          description:  Timestamp (as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)) of when the charging should end  
        stopChargeStatus:
          type: string
          description: | 
                        Status of delayed stop charge.
                        one of following enums status will be set:
                          | Enum | Description |
                          |----------|:-------------:|
                          | Deactivated | Function is deactivated |
                          | Activated | The function is activated, and the conditions to execute it are met. |
                          | Successful | The most recent stop charge was successful. |
                          | StopChargeFailed | Failed to stop charging. |
                          | ChargeEndTimeScheduleFailed| The programming of the end of charge failed; the charging should not stop at the requested time. |
                                                              
          enum:
               - Deactivated
               - Activated
               - Successful
               - StopChargeFailed
               - ChargeEndTimeScheduleFailed  
        schedule:
            properties:
              programs:
                type: array
                items:
                    $ref: '#/components/schemas/ChargeScheduleProgram'
        type:
          description: Charging type associated to the vehicle. Full means that the charge will stop when it is completed whereas partial will stop before end of charge in order to optimize battery lifetime.
          type: string
          enum: [ Partial, Full ]

                      
    EnergyBatteryBase:
      type: object
      description: Electric charging state.
      properties:
        capacity:
          description: Electric battery total capacity (expressed in Wh). 
          type: number
          format: float
          deprecated : true
        load : 
          $ref: '#/components/schemas/LoadElectricEnergy'
        health: 
          $ref: '#/components/schemas/HealthElectricEnergy'
    EnergyBattery:
      type: object
      description: Electric charging state.
      properties:
        capacity:
          description: Electric battery total capacity (expressed in Wh). 
          type: number
          format: float
          deprecated : true
        load : 
          allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - $ref: '#/components/schemas/LoadElectricEnergy'
          required : [createdAt]
        health:
          allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - $ref: '#/components/schemas/HealthElectricEnergy'
          required : [createdAt]
    HealthElectricEnergy:
      type: object
      properties:
        capacity:
          description:  Health related to battery capacity (expressed in percentage).
          type: integer
          minimum: 0
          maximum: 100
        resistance:
          description:  Health related to battery resistance (expressed in percentage).
          type: integer
          minimum: 0
          maximum: 100
          
    LoadElectricEnergy : 
      properties : 
        capacity:
          description: Electric battery total capacity (expressed in Wh). 
          type: integer
        residual:
          description: Residual electric energy (expressed in Wh)
          type: integer
    ChargeScheduleProgram:  
     allOf:
        - $ref: '#/components/schemas/BasicProgram'
        - properties:
                enabled:
                  type: boolean
                  description:  Determines whether this program is enabled or not.
                end:
                  type: string
                  description: |
                          The program relative (to 00:00) end time formatted using the duration format based on [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) with the schema: P[n]Y[n]M[n]DT[n]H[n]M[n]S
                      
                          _example_: 
                        
                          * PT14H30M means 14H and 30Min
                  example : PT14H30M
                chargeUntilFull:
                    description: If this program is tagged as chargin until battery is full.
                    type : boolean
                
    BasicProgram:
      type: object
      description: Describe recurring action.
      properties:
        start:
            type: string
            description: |
                          The program relative (to 00:00) start time formatted using the duration format based on [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) with the schema: P[n]Y[n]M[n]DT[n]H[n]M[n]S
                      
                          _example_: 
                        
                          * PT14H30M means 14H and 30Min
            example : PT14H30M
        occurence:
                type: object
                description: >
                   The occurrence on the program will spread on days depending on recurrence value.
                properties:
                    day:
                        type: array
                        items:
                          type: string
                          enum: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
                required: [day]
      required: [start]
    Program:
      type: object
      description: Describe recurring action.
      allOf:
        - $ref: '#/components/schemas/BasicProgram'
        - properties:
            recurrence:
                description: | 
                          Determines the recurrence of the program. 
                          * None: means no recurrence. 
                          * Daily: repeated over the week. 
                type: string
                enum: [None, Daily]
                default: Daily
    TelemetryExtension:
        allOf:
          - description: Additional data set for telemetry.  
          - properties:
                location:
                  $ref: '#/components/schemas/PositionBase'
                maintenance:
                  $ref: '#/components/schemas/MaintenanceBase'

    PreconditioningProgram:
      allOf:
        - $ref: '#/components/schemas/Program'
        - title: PreconditionProgram
        - properties:
            enabled:
                type: boolean
                description:  Determines whether this program is enabled or not.
            
            slot:
              description: The preconditioning program number.
              type: integer
              
        - required: [enabled]
        
    TimeTriggerEntry:
      allOf:
        -  $ref: '#/components/schemas/Program'
        - required: [start]
        - description: |
                        The monitor Time Trigger Entry that specifies the start (relative or absolute) and duration of the time interval. The relative start time must be to midnight and the absolute must be expressed in UTC.
                        
                        <u><b>Note:</b></u> 
                        * ```occurence``` field <b><u>should</u></b> be provided only if the recurrence is set to ```Daily```. Otherwise an invalid parameter status is returned.
                        * The time entry with recurrence set to ```None``` means that this program will be enabled from the absolute start time with no recurrence. This kind of time entry can be used to for delayed monitor activation (from a start time) or a closed trigger time interval.
                        *  ```duration``` field <b><u>is mandatory</u></b> if the recurrence is set to ```Daily```. If it is set to ```None``` then it will define the absolute monitor activity period duration (starting from absolute time defined by ```start``` field), otherwise this trigger time interval is considered as unclosed.
        ##
          properties:
            duration:
              description: Duration of the monitor action expressed using [ISO-8601 Duration spec](https://en.wikipedia.org/wiki/ISO_8601#Durations).  This field <b><u>is mandatory</u></b> if the recurrence is set to ```Daily```
              type: string
              example: PT04H30M
            start:
              type: string
              description: |
                            The start time.
                            Its format depends on the recurrence value.
                            * For ```None``` recurrence, the start time is considered as absolute time from when the monitor can trigger events. In this case the format should be compliante with [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)  
                            
                              _example_: 2018-01-03T12:00:00+01:00
                            * For ```Daily``` recurrence, the start time formatted using the duration format based on [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) with the schema: P[n]Y[n]M[n]DT[n]H[n]M[n]S and whose value is between 00H and 23h59
                        
                              _example_: PT14H30M : means 14H30min
            occurence:
                  type: object
                  description: >
                     The occurrence on a bounded program will spread on months, weeks, days depending on recurrence value and ```week``` field.
                  properties:
                      day:
                          type: array
                          minItems: 1
                          maxItems: 7
                          items:
                            type: string
                            enum: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
                      week:  
                          description:  occurences over the weeks of the year from w1 to w52 specified in an array unitary or grouped by ranges (w1, w2, w34-w46, w52)
                          type: array
                          minItems: 1
                          maxItems: 52
                          items:
                          #week of year : w1, w2 ... w34-w46 ..
                            type: string
                            format: '[wW][1-5][0-9]?(-[wW][1-5][0-9]?)?'
                          example: [w1-w25,w30,w36, w40-w50]
          example:  
            recurrence: Daily
            start: PT8H30M
            duration: PT7H30M
            occurence: [Mon,Tue,Thu, Fri]
          
    Preconditioning:
      type: object
      description: Preconditioning the vehicle for driver and passenger.
      properties:
        airConditioning:
          allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - type : object
            - properties:
                updatedAt:
                  type: string
                  format: date-time
                  deprecated: true
                status:
                  description: The status of the preconditioning feature.
                  type: string
                  enum: [Enabled, Disabled, Finished, Failure]
                startingCause:
                  description : starting cause
                  type: string
                  enum: [Immediate, Scheduled]
                failureCause:
                  description: failure cause
                  type: string
                  enum: [ Defect, DoorOpened, LowBattery, LowFuelLevel, TooManyUnusedProg, WindowsRoofOpened, HoodOpened, NotParked, OtherFailures ]
                programs:
                  type: array
                  items:
                    $ref: '#/components/schemas/PreconditioningProgram'
          required : [ createdAt]
    
    PreconditioningBase:
      type: object
      description: Preconditioning the vehicle for driver and passenger.
      properties:
        airConditioning:
          allOf:
            - type : object
            - properties:
                updatedAt:
                  type: string
                  format: date-time
                  deprecated: true
                status:
                  description: The status of the preconditioning feature.
                  type: string
                  enum: [Enabled, Disabled, Finished, Failure]
                  example : Enabled
                startingCause:
                  description : starting cause
                  type: string
                  enum: [Immediate, Scheduled]
                  example : Immediate
                failureCause:
                  description: failure cause
                  type: string
                  enum: [ Defect, DoorOpened, LowBattery, LowFuelLevel, TooManyUnusedProg, WindowsRoofOpened, HoodOpened, NotParked, OtherFailures ]
                  example : OtherFailures
                programs:
                  type: array
                  items:
                    $ref: '#/components/schemas/PreconditioningProgram'
          required : [ createdAt]

    Environment: 
              type: object
              properties:
                  luminosity:
                     $ref: '#/components/schemas/Luminosity'
                  air:
                     $ref: '#/components/schemas/Air'
    EnvironmentBase: 
              type: object
              properties:
                  luminosity:
                     $ref: '#/components/schemas/LuminosityBase'
                  air:
                     $ref: '#/components/schemas/AirBase'
    Luminosity:
                    allOf:
                      - $ref: '#/components/schemas/CreatedAtField'
                      - $ref: '#/components/schemas/LuminosityBase'
                    required : [ createdAt]
    LuminosityBase:
                    type: object
                    properties:
                      day:
                        type: boolean 
                        example : true
    Air:
                    allOf:
                      - $ref: '#/components/schemas/CreatedAtField'
                      - $ref: '#/components/schemas/AirBase'
                    required : [ createdAt]
    AirBase:
                        type: object
                        description: Outside air temperature in Celsius degrees
                        properties:
                          temp:
                            type: number
                            format : float
                            example : 33,3
    Trip: 
      allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - $ref: '#/components/schemas/UpdatedAtField'
            - title: Trip 
              type: object
              properties:
                _links:
                  type: object
                  properties:
                    self:
                      $ref: '#/components/schemas/link'
                    vehicle:
                      $ref: '#/components/schemas/link'
                    waypoints:
                      $ref: '#/components/schemas/link'
                    alerts:
                      $ref: '#/components/schemas/link'
                    collisions:
                      $ref: '#/components/schemas/Link'
                  required : [self]
                id:
                  type: string
                  description: Identifier of a trip
                createdAt:
                  type: string
                  format: date-time
                updatedAt:
                  type: string
                  format: date-time                  
                startedAt:
                  type: string
                  format: date-time
                  description: Date & Time when the trip started
                stoppedAt:
                  type: string
                  format: date-time
                  description: Date & Time when the trip stopped
                startPosition:
                  $ref: '#/components/schemas/Position'
                stopPosition:
                  $ref: '#/components/schemas/Position'
                duration:
                  type: integer
                  description: Duration in second of the trip
                distance:
                  type: number
                  format: float
                  minimum: 0.0
                  description: Distance in km of the trip
                startMileage: 
                  type: number
                  format: float
                  description: Vehicle mileage at the trip starting time. 
                startEnergies: #LiteEnergy
                  description: Vehicle energies levels and autonomies at the trip start time. 
                  type: array
                  items: 
                     $ref: '#/components/schemas/LiteEnergy'
                endEnergies: #LiteEnergy
                  description: Vehicle energies levels and autonomies at the trip end time. 
                  type: array
                  items: 
                     $ref: '#/components/schemas/LiteEnergy'                     
                energyConsumptions:
                  description: The consumptions of different energies during this trip.
                  type: array
                  items: 
                     $ref: '#/components/schemas/EnergyConsumption'
                kinetic:
                  description: Expresses the max and average vehicle speed during this trip. 
                  type: object
                  properties:
                    avgSpeed: 
                      type: number
                      format: float
                    maxSpeed: 
                      type: number
                      format: float
                segments:
                  description: The parts of the trip crossed for each type of propulsion.
                  type: array
                  items:
                    $ref: '#/components/schemas/TripSegment'
                done:
                  description: Determines either this trip is finished or not.
                  type: boolean
                  example : true
                faults:
                  description: Faults of this finished or in progress trip. This means that we lacked data from the vehicle to complete the trip description during one of its step (starting, progressing, or finishing).
                  type: array
                  items:
                    type: object
                    properties:
                      fault:
                        type: string
                        enum: [Unstarted, DataLacking, Unfinished]
                        example : DataLacking
                      cause:
                        type: string
                        enum: [GeoPrivacy, FullPrivacy, Connection]
                        example : Connection
              required : [_links, createdAt, id]
    TripSegment:
      description: Part of the trip crossed for a type of propulsion.
      properties:
        propulsion: 
          description: |
            Propulsion during this trip segment.
          type: string
          enum: [Thermal, Electric, Hybrid]
        percent:
          description: | 
            Trip segment pecentage. _Unit: %_
          type: number
          format: float
        distance:
          description: |
            Distance driven during this trip segment. _Unit: Km_
          type: number
          format: float
          
    User: 
      allOf:
            - $ref: '#/components/schemas/UpdatedAtField'
            - $ref: '#/components/schemas/CreatedAtField'
            - title: User Information
              type: object
              properties:
                _links:
                  type: object
                  properties:
                    self:
                      $ref: '#/components/schemas/link'
                    vehicles:
                      $ref: '#/components/schemas/link'
                email:
                  description: Mail of user
                  type: string
                firstName:
                  description: First name of user
                  type: string
                lastName:
                  description: Last name of user
                  type: string
                _embedded:
                  type: object
                  properties:
                    Vehicles:
                      type: array
                      items:
                        $ref: '#/components/schemas/Vehicle'
    Vehicle: 
      allOf:
        - $ref: '#/components/schemas/UpdatedAtField'
        - $ref: '#/components/schemas/CreatedAtField'
        - title: Vehicle Information
          type: object
          properties:
            _links:
              type: object
              properties:
                  self:
                    $ref: '#/components/schemas/Link'
                  user:
                    $ref: '#/components/schemas/Link'  
                  lastPosition:
                    $ref: '#/components/schemas/Link'
                  trips:
                    $ref: '#/components/schemas/Link'
                  maintenance:
                    $ref: '#/components/schemas/Link'
                  alerts:
                    $ref: '#/components/schemas/Link'
                  status:
                    $ref: '#/components/schemas/Link'
                  telemetry:
                    $ref: '#/components/schemas/Link'
                  collisions:
                    $ref: '#/components/schemas/Link'
                  alarms:
                    $ref: '#/components/schemas/Link'
                  monitors:
                    $ref: '#/components/schemas/Link'
                  remotes:
                    $ref: '#/components/schemas/Link'
                  callbacks:
                    $ref: '#/components/schemas/Link'
              required : [self]
            id:
              type: string
              example : 01234a91598cf0c57e856bb88003fd2a7f2c27f458faab8bbd34356235695902ffb6c4c5360d6714415ab92b07c8e33b5
            vin:
              description: Serial number of a vehicle
              type: string
              example : VF3ABCDE0FG123456
            motorization :
              description : Motorization of the vehicle.
              type : string
              enum: [Electric, Hybrid, Thermic, Hydrogen]
              example : Thermic
            callCenter : 
              type: object
              properties:
                  stolen: 
                    $ref: '#components/schemas/StolenCallCenter'
            brand:
              deprecated : true
              description: Brand of a vehicle
              type: string
              example : Peugeot
            label:
              deprecated : true
              description: Version of a vehicle
              type: string
            pictures:
              deprecated : true
              description: Link to a vehicle picture. 
              type: array
              minItems: 1
              maxItems: 12
              items:
                $ref: '#/components/schemas/Url' 
              example: 
                - "https://visuel3d-secure.peugeot.com/V3DImage.ashx?client=miseco&format=png&back=0&version=1PP5C5ZNKAB0A0B0&color=0MM00N9V&trim=0PDB0RFX&OPT1=D180&OPT2=D190&OPT3=DD50&OPT4=DLZ0&OPT5=DVB1&view=001"
                - "https://visuel3d-secure.peugeot.com/V3DImage.ashx?client=miseco&format=png&back=0&version=1PP5C5ZNKAB0A0B0&color=0MM00N9V&trim=0PDB0RFX&OPT1=D180&OPT2=D190&OPT3=DD50&OPT4=DLZ0&OPT5=DVB1&view=002"
            _embedded:
              type: object
              properties:
                extension:
                  $ref: '#/components/schemas/VehicleExtension'
          required : [_links]
    VehicleExtension:
        allOf:
          - description: Additional vehicle  information.  
          - properties:
                onboardCapabilities:
                  $ref: '#/components/schemas/OnboardCapabilities'
                branding:
                  $ref: '#/components/schemas/VehicleBranding'
                pictures:
                  $ref: '#/components/schemas/VehiclePictures'
      
    StolenCallCenter:
      type: object
      description : Call center information to manage stolen vehicle request (only return when country query paarameter is filled and your account have apprioriate rights).
      properties : 
        countryCode:
          $ref: '#/components/schemas/CountryEnum'
          type : string
        phoneNumber:
          type : string
          description: Phone number information of the dedicated call center.
    OnboardCapabilities:
      type : object
      properties:
        data :
          description : List of retrievable data represented by their scopes.
          type: array
          items:
            type: string
            enum:
              - data:vehicle:devices:pnc
              - data:telemetry
              - data:telemetry:environment
              - data:telemetry:privacy
              - data:telemetry:vehicle
              - data:telemetry:vehicle:ignition
              - data:telemetry:vehicle:preconditioning
              - data:telemetry:vehicle:energies
              - data:telemetry:vehicle:engines
              - data:telemetry:vehicle:doorsState
              - data:telemetry:vehicle:powertrain
              - data:telemetry:vehicle:battery
              - data:telemetry:vehicle:safety
              - data:telemetry:vehicle:odometer
              - data:telemetry:vehicle:kinetic
              - data:telemetry:vehicle:transmission
              - data:telemetry:vehicle:adas
              - data:telemetry:vehicle:lightingSystem
              - data:telemetry:vehicle:maintenance
              - data:telemetry:vehicle:drivingBehavior
              - data:telemetry:vehicle:wipingBlades
              - data:telemetry:vehicle:alarm
              - data:position
              - data:trip
              - data:alert
              - data:collision
        remote:
          description : List of callable remote functions and associated supported properties.
          type: object
          required: [preconditioning,door,horn,charging,lights,wakeup,navigation]
          properties:
            preconditioning:
              required: [supported, scopeName, parameters]
              type: object
              properties:
                supported :
                  type: boolean
                  description: True means remote preconditioning is supported.
                scopeName:
                  type: string
                  enum: [remote:preconditioning:write]
                  default : remote:preconditioning:write
                parameters:
                  type: object
                  properties:
                    programs:
                      type : object
                      properties:
                        size: 
                          type: integer
                          description : Max number of program accepted by the vehicle.
                      required : [size]
                    immediate:
                      type: boolean
                      description: True means remote preconditioning immediate action is supported.
                      example : true
            charging:
              type: object
              required: [supported, scopeName, parameters]
              properties:
                supported :
                  type: boolean
                  description: True means remote charging is supported.
                scopeName:
                  type: string
                  enum: [remote:charging:write]
                parameters:
                  type: object
                  properties:
                    immediate: 
                        properties:
                          start:
                            type: boolean
                            description: True means remote immediate charge start action is supported.
                            example : true
                          stop:
                            type: boolean
                            description: True means remote immediate charge stop action is supported. 
                            example : stop
                    schedule:
                      required: [programs,nextDelayedTime,preferences]
                      properties:
                        programs:
                          type: object
                          properties:
                            supported :
                              type : boolean
                              description: True means remote charging schedule[programs] is supported.
                            size: 
                              type: integer
                              description : Max number of program accepted by the vehicle.
                          required : [supported]
                        nextDelayedTime:
                          type: boolean
                          description: True means remote charging schedule[nextDelayedTime] is supported.
                    preferences:
                      properties:
                        level:
                          type: boolean
                          description: True means remote charging preferences[level] is supported.
                        type:
                          type: boolean
                          description: True means remote charging preferences[type] is supported.
            door:
              type: object
              required: [supported, scopeName]
              properties:
                supported :
                  type: boolean
                  description: True means remote door is supported.
                  example : true
                scopeName:
                  type: string
                  enum: [remote:door:write]
                  default : remote:door:write
            horn:
              type: object
              required: [supported, scopeName]
              properties:
                supported :
                  type: boolean
                  description: True means remote horn is supported.
                  example : true
                scopeName:
                  type: string
                  enum: [remote:horn:write]
                  default : remote:horn:write
            lights:
              type: object
              required: [supported, scopeName]
              properties:
                supported :
                  type: boolean
                  description: True means remote lights is supported.
                  example : true
                scopeName:
                  type: string
                  enum: [remote:lights:write]
                  default : remote:lights:write
            wakeup:
              type: object
              required: [supported, scopeName]
              properties:
                supported :
                  type: boolean
                  description: True means remote wakeup is supported.  
                  example : true
                scopeName:
                  type: string
                  enum: [remote:wakeup:write]
                  default : remote:wakeup:write
            navigation:
              type: object
              required: [supported, scopeName]
              properties:
                supported :
                  type: boolean
                  description: True means remote navigation is supported.
                  example : false
                scopeName:
                  type: string
                  enum: [remote:navigation:write]
                  default : remote:navigation:write
    VehicleExtensionType:
      type: array
      minItems: 1
      maxItems: 3
      items:
        type: string
        enum:
          - onboardCapabilities
          - branding
          - pictures
    VehicleBranding:
      type : object
      properties:
        brand:
          description: Brand of a vehicle
          type: string
          example : Peugeot
        label:
          description: Car model description.
          type: string
    VehiclePictures:
      description: Link to a vehicle picture. 
      type: array
      minItems: 1
      maxItems: 12
      items:
        $ref: '#/components/schemas/Url' 
      example: 
        - "https://visuel3d-secure.peugeot.com/V3DImage.ashx?client=miseco&format=png&back=0&version=1PP5C5ZNKAB0A0B0&color=0MM00N9V&trim=0PDB0RFX&OPT1=D180&OPT2=D190&OPT3=DD50&OPT4=DLZ0&OPT5=DVB1&view=001"
        - "https://visuel3d-secure.peugeot.com/V3DImage.ashx?client=miseco&format=png&back=0&version=1PP5C5ZNKAB0A0B0&color=0MM00N9V&trim=0PDB0RFX&OPT1=D180&OPT2=D190&OPT3=DD50&OPT4=DLZ0&OPT5=DVB1&view=002"
    Alerts:
      title: Alerts Array
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                alerts:
                  type: array
                  items:
                    $ref: '#/components/schemas/Alert'

    Collisions:
      title: Vehicle Collisions array
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                Collisions:
                  type: array
                  items:
                    $ref: '#/components/schemas/Collision'
  
    WayPoints:
      description: WayPoints of a Trip response
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                positions:
                  type: array
                  items:
                    $ref: '#/components/schemas/Position'
              required:
                  - positions
                  
                  
    Telemetry:
        allOf:
            - $ref: '#/components/schemas/CreatedAtField'
            - type: object
              properties:
                _links:
                  type: object
                  properties:
                    self:
                      $ref: '#/components/schemas/Link'
                    vehicle:
                      $ref: '#/components/schemas/Link'
                    trip:
                      $ref: '#/components/schemas/Link'
                  required: [self]
                privacy:
                  $ref: '#/components/schemas/PrivacyBase'
                vehicle:
                  type: object
                  properties:
                    engines:
                      type: array
                      items:
                        $ref: '#/components/schemas/EngineBase'
                    energies:
                      type: array
                      items:
                        $ref: '#/components/schemas/EnergyBase'
                    transmission:
                      $ref: '#/components/schemas/Transmission'
                    powertrain: 
                      $ref: '#/components/schemas/PowertrainBase'
                    adas:
                      $ref: '#/components/schemas/Adas'
                    lightingSystem:
                      $ref: '#/components/schemas/LightingSystemBase' 
                    ignition:
                       $ref: '#/components/schemas/IgnitionBase'
                    doorsState:
                      $ref: '#/components/schemas/DoorsStateBase'  
                    battery:
                      $ref: '#/components/schemas/BatteryBase'
                    safety:  
                      $ref: '#/components/schemas/BaseSafety'
                    wipingBlades:  
                      $ref: '#/components/schemas/WipingBladesState'
                    odometer: 
                        type: object
                        properties:
                          mileage:
                                description: Vehicle mileage expressed in KM.
                                type: number
                                format: float
                                minimum : 0.0
                    kinetic :
                        $ref: '#/components/schemas/BasicKinetic'
                    drivingBehavior:
                      $ref: '#/components/schemas/DrivingBehaviorBase'
                    alarm:
                        $ref: '#/components/schemas/BaseAlarm'
                environment:
                  $ref: '#/components/schemas/EnvironmentBase'
                _embedded:
                  type: object
                  properties:
                    extension:
                       $ref: '#/components/schemas/TelemetryExtension'
              required: [_links]
    
    Telemetries:
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                telemetries:
                  type: array
                  items:
                    $ref: '#/components/schemas/Telemetry'

          
    TelemetryExtensionType:
      type: array
      minItems: 1
      maxItems: 2
      items:
        type: string
        enum:
          - location
          - maintenance
  
    Trips:
      title: Trips
      description: List of a Trips response
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - description: List of a Trips response
          properties:
            _links:
              $ref: '#/components/schemas/Tab_Links'
            total:
              type: integer
            totalPage:
              type: integer
            currentPage:
              type: integer
            _embedded:
              type: object
              properties:
                trips:
                  type: array
                  items:
                    $ref: '#/components/schemas/Trip'
    Vehicles:
      title: Vehicle Information
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - title: Vehicle List
          properties:
            _embedded:
              type: object
              properties:
                vehicles:
                  type: array
                  items:
                    $ref: '#/components/schemas/Vehicle'
                

    url:
      type: string
      description: URL format follows [RFC 3986](https://tools.ietf.org/html/rfc3986) and
        usually looks like this ` scheme://host[:port][/Path] `
      example : http://example.com
    link:
      type: object
      description: A Link Object as defined by [JSONHAL#Link
        Object](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5).
      required:
        - href
      properties:
        href:
          $ref: '#/components/schemas/url'
        templated:
          type: boolean
          description:  SHOULD be true when the Link Object's "href"   property is a URI
            Template
        type:
          type: string
          description:  a hint to indicate the media type  expected when dereferencing the
            target resource.
        deprecation:
          allOf:
            - $ref: '#/components/schemas/url'
            - description: indicates that the link is to be deprecated (i.e. removed) at a
                future date.  Its value is a URL that SHOULD provide further
                information about the deprecation.
        name:
          type: string
        title:
          type: string
          description: Its value is a string and is intended for labelling the link with a
            human-readable identifier (as defined by
            [RFC5988](https://tools.ietf.org/html/rfc5988)).
        profile:
          type: string
          description: Its value is a string and is intended for indicating the language of
            the target resource (as defined by [RFC5988]).
        hreflang:
          type: string
          description: Its value is a string which is a URI that hints about the profile
            (as defined by
            [I-D.wilde-profile-link](https://tools.ietf.org/html/draft-kelly-json-hal-08#ref-I-D.wilde-profile-link))
            of the target resource.

    ChargingStatusEnum:
      description: status of charging system.
      type: string
      enum:  [Disconnected, InProgress, Failure, Stopped, Finished]      
    AlertMsgEnum:
      type: string   
      description: Alert list 
      enum:
        - AbsBrakingSystemFault    
        - ActiveSpoilerFault    
        - AdBlueFault     
        - AdBlueFaultStartingImpossible   
        - AdBlueFaultStartingImpossibleSoon  
        - AddWasherFluid     
        - AirbagOrSeatBeltPretensionerOrActiveHoodFailure 
        - AssistanceButtonFault    
        - AutomaticBrakingDeactivated   
        - AutomaticHeadlightAdjustmentFault   
        - BatteryChargeOrElectricalCircuitSystemFailure 
        - BrakingSystemFailure    
        - ChargingFailure     
        - CheckTheCenterBrakeLamp    
        - CollisionDetectionSystemFault   
        - CollisionMitigationSystemFault   
        - CoolantLevellow     
        - DrivingAssistanceSensorBlind   
        - ElectricTractionSystemFailureLimitSpeed
        - ElectricTractionSystemFailureStopVehicle
        - ElectricTractionSystemFault
        - ElectronicImmobiliserFault    
        - EmissionSystemOrAdBlueQualityFailueStartingImpossible
        - EmissionSystemOrAdBlueQualityFailueStartingImpossibleSoon
        - EmissionSystemOrAdBlueQualityFailure  
        - EngineFailure     
        - EngineFault
        - EngineMisfiringFuel
        - EngineOilPressureFailure    
        - EngineTemperatureFailure    
        - EspAsrSystemFault     
        - FrontLeftFlashingIndicatorFault   
        - FrontLeftFogLampsFault     
        - FrontLeftParkingLampsFault     
        - FrontRightFlashingIndicatorFault   
        - FrontRightFogLampsFault     
        - FrontRightParkingLampsFault     
        - FuelLevelLow     
        - GearboxFault     
        - HeadlightsFault     
        - InstalledSpareWheelFault   
        - InterVehicleTimeMeasurementFault  
        - LaneChangeAssistanceFault     
        - LaneDepartureWarningSystemFault   
        - LeftBrakeLampFault  
        - LeftFrontDoorOpen     
        - LeftFrontDoorOpenLowSpeed 
        - LeftFrontTirePressurSensorFault   
        - LeftFrontTirePuncture    
        - LeftFrontTireUnderInflated    
        - LeftRearDoorOpen     
        - LeftRearDoorOpenLowSpeed
        - LeftRearTirePressurSensorFault   
        - LeftRearTirePuncture    
        - LeftRearTireUnderInflated    
        - LeftReverseLampFault     
        - OilLevelLow      
        - ParkAssistSystemFault    
        - ParkingBrakeOrHillStartSystemFailure  
        - ParticleFilterAdditiveLevelTooLow   
        - ParticleFilterFull     
        - ParticleFilterRegenerating    
        - PowerSteeringFailure    
        - PowerSteeringFault    
        - PreheatingPreventilationDeactivatedBatteryLow 
        - PreheatingPreventilationDeactivatedClockUnset 
        - PreheatingPreventilationDeactivatedFuelLevelLow 
        - RearLeftFlashingIndicatorFault   
        - RearLeftFogLampsFault     
        - RearLeftParkingLampsFault     
        - RearRightFlashingIndicatorFault   
        - RearRightFogLampsFault     
        - RearRightParkingLampsFault     
        - RearWindowOpen     
        - RearWindowOpenLowSpeed
        - ReplaceBrakePads     
        - ReplaceTheRemoteControlBattery   
        - RetractableRoofMechanismFault   
        - RightBrakeLampFault     
        - RightFrontDoorOpenLowSpeed    
        - RightFrontDoorOpen     
        - RightFrontTirePressurSensorFault  
        - RightFrontTirePuncture    
        - RightFrontTireUnderInflated    
        - RightRearDoorOpen     
        - RightRearDoorOpenLowSpeed 
        - RightRearTirePressurSensorFault   
        - RightRearTirePuncture    
        - RightRearTireUnderInflated    
        - RightReverseLampFault     
        - RiskOfIce     
        - RoofOperationNotPossibleSpeedUnknown
        - RoofOperationNotPossibleTooHighTemp
        - ShiftToPark     
        - SteeringLockFault     
        - SuspensionFault     
        - SuspensionFaultLimitSpeed
        - SuspensionFaultRepaireVehicle
        - TireUnderInflationDetectionSystemFault  
        - TooManyRoofOperation
        - TrailerConnectionFault    
        - TrunkOrHoodOpen     
        - TrunkOrHoodOpenLowSpeed
        - WaterInTheDieselFuelFilter  
      example : FuelLevelLow 

    CountryEnum:
      type: string
      description: Country code as defined in ISO 3166-1 alpha-2.
      enum:
        - CL
        - BR
        - AR
        
    TelemetryEnum:
      type: array
      minItems: 1
      maxItems: 15
      items:
        type: string
        enum:
          - environment
          - privacy
          - vehicle
          - vehicle.adas
          - vehicle.battery
          - vehicle.doorsState
          - vehicle.energies
          - vehicle.engines
          - vehicle.ignition
          - vehicle.lightingSystem
          - vehicle.safety
          - vehicle.transmission
          - vehicle.alarm.status
          - vehicle.alarm.trigger
          - vehicle.wipingBlades
          
    AlarmTypeEnum:
      type: array
      items:
        type: string
        enum:
          - vehicle.alarm.status
          - vehicle.alarm.trigger
    EnergyType:
          type: string
          description: Energy type present on the vehicle.
          enum: [Fuel, Electric]
    EnergySubType:
          type: string
          description: | 
            Energy subtype. This field is not mandatory and therefore if it is not present, it means that the resource consumer should only process the primary energy type. The enumeration of the subtypes is not exhaustive and may contain more elements depending on the evolution of the vehicles. The consumer of the data must take this constraint into account. The Fossil and Electric energy subtypes are only used to populate this subtype for the default Fuel and Electric types.
              * Electric and hydrogen type are considered as low emission vehicle whereas fuel(fossil) is associated to thermic energy
          enum: [FossilEnergy, ElectricEnergy, Hydrogen] 
    Range:
      type: string
      pattern: \d+-\d*
      default: 0-
      description: >
        value range
    
    TripStateEnum:
         type: string
         enum: [Nominal,Unstarted, DataLacking, Unfinished]
    TripStateEnumArray:
      type: array
      items:
         $ref: '#/components/schemas/TripStateEnum'
#        
    xError:
      type: object
      description: Detailed error
      properties:
        code:
          type: integer
        debug:
          type: string
        message:
          type: string
      example:
        code: 1001
        debug: CMP_001234
        message: No data availble for such context.
        
    UpdatedAtField:
     type: object
     properties:
       updatedAt:
          description: Date when the resource has been updated.
          type: string
          format: date-time
  
    CreatedAtField:
       type: object
       properties:
          createdAt:
            description: Date when the resource has been created.
            type: string
            format: date-time      
    MonitorId:
      type: string
      description: Uniq monitor ID returned when the monitor was created succefully.    
    Attribute:
            type: object
            properties:
              type:
                type: string
                enum: [Header, Body, Query]
                description: |
                  3 attributes type:
                  
                  |Attribute-type|Role|
                  |----------|-------------|
                  |Header|-Will be add as http header extension "x-######:"|
                  |Body|-Will be simply add to event body map attribute (see monitor event definition in template document)|
                  |Query|-Will set as http query parameter when invoking the Webhook|
              key:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: string
                    enum: [Vin,CallbackID,CallbackLabel]
                    description: |
                      A value  that will be associated with the provided key as is if expressed as literal value or  contextually valued if prefixed with the dollar sign ($).  
                      
                      * example: Having a vin=VIN123456, the following attribute set:
                              ```"attributes": [
                                  {
                                    "type": "Header",
                                    "key": "X-vehicle-id"
                                    "value":"$vin"
                                  }
                                ]```
                        will be valued as http header extension: 
                                
                        *"X-vehicle-id: VIN123456"*
            required:
              - key
              - value  
              - type
            example:
              type: Header
              key: X-Vehicle_Id
              value: $vin
              
    AttributeSet:          
          type: array
          description: Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a header enhancement (such as headers can be used as an authentication parameter when posting the event) or simply added to the notification event body (as set of key/values) or finally as additional query parameters.
          items:
            $ref: '#/components/schemas/Attribute'


    WSAttribute:
      allOf:
        - $ref: '#/components/schemas/Attribute'
        - properties:
              type:
                type: string
                description: Websocket basic key/value available as body attribute only. 
                enum: [Body]
                default: Body
              
                        
    WSAttributeSet:          
          description:  Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a paylod key/value map enhancement or simply added to the notification event body (as set of key/value).
          type: array
          items:
            $ref: '#/components/schemas/WSAttribute'
    
    PushNotifAttribute:
      allOf:
        - properties:
              type:
                type: string
                description: Push notification basic key/value. The key should not be a reserved word ("from", "message_type", or any word starting with "google" or "gcm"). The header attribute are mapped to data key/value map. 
                enum: [Header,Body]
                default: Header
              value:
                oneOf:
                  - type: string
                    description: |
                         The key/value pair is included as is in the generic 'data' part of the notification If the key is not a reserved one and type is not ```Body```, otherwise, it  will be added as the the corresponding field of the [push-notification spec](https://firebase.google.com/docs/cloud-messaging/concept-options#customizing-a-message-across-platforms) of output message (at notification time).
                         
                        
                 
                            ## Keywords:  
                             Those keywords, FCM and MPH, can be used to customize notification messages and then used to customize the Firebase notification .
                            > * _Those attribute keys are optional but should be provided with their valid values with the respect of the format (see the table below) if set._

                            | Key   |      Category      |  Description |  Format |
                            |----------|:-------------:|------:|------:| 
                            | disableNotificationPayload | iOS, Android and WebPush |If set to true, will remove ```notification ``` payload from the Firebase body when sending event message to Firebase. | ```"true"``` or  ```"false"```|
                            | deliveryPriority |iOS, Android and WebPush only|Define the message delivery priority for Android and WebPush platforms. It will be mapped on the FCM field: (Android > ```"priority"```), (iOS > ```"apns-priority"```) and (WebPush > ```"Urgency"```). |```"low"```, ```"normal"``` or  ```"high"```. (<b>note:</b> ```"low"``` will be mapped on normal (lowest level) on android and web push platforms)|
                            | mutable | iOS only|Set the apns payload mutable or not.  It will be mapped on the FCM field ```"mutable-content"```. For more details, see [FCM Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref).  |```"true"``` or  ```"false"```|
                            | contentAvailable |iOS only |this field to represent ```"content-available"``` in the APNs payload. It's used (<i>true value</i>) to wakeup an inactive client app. For more details, see [FCM Protocol](https://firebase.google.com/docs/cloud-messaging/http-server-ref)|```"true"``` or  ```"false"```|                            
                            | title | iOS, Android and WebPush |Title of the notification|not empty string|
                            | body | iOS, Android and WebPush|The notification's body text|not empty string|
                            | image| iOS, Android and WebPush |URL of the image displayed in a notification |not empty URL string [RFC 3986](https://tools.ietf.org/html/rfc3986)  (scheme://host[:port][/Path]|
                            | sound | iOS, Android |Specifying the sound to play when the device receives the notification|not empty string|
                            | clickAction | Android|The action associated with a user click|not empty string|
                            | ttl | iOS, Android and WebPush|How long (in seconds) the message should be kept in FCM storage if the device is offline|not empty string: format $(int) - pattern '^\d+$'  |
                            | bodyLocKey | iOS and Android|The key to the body string in the app's string resources|not empty string|
                            | bodyLocArgs | iOS and Android |Variable string values to be used in place of the format specifiers in body_loc_key|not empty string. <b>Args are separated by comma (,) if several</b>|
                            | titleLocKey | iOS and Android |The key to the title string in the app's string resources |not empty string|
                            | titleLocArgs | iOS and Android |Variable string values to be used in place of the format specifiers in title_loc_key. <b>Args are separated by comma (,) if several</b>|
                            | badge | iOS and WebPush |The value of the badge on the home screen app icon|not empty string (integer) format|
                            | icon | Android and WebPush |The notification's icon|not empty string format|
                            | tag | Android and WebPush |Identifier used to replace existing notifications in the notification drawer.|not empty string format|
                            *For more details of the FCM Apns, Android or Webpush message keys, refer to Firebase Google documentation.
                            
                  - type: string
                    enum: [Vin,CallbackID,CallbackLabel]
                    description: |
                      Set of variables that will be contextually valued and used as push notification data or body attribute value.

                      *To reference the variable, prefix its name with the dollar sign ($)*
                      
                     
                      * example: Having a vin=VIN123456, the following attribute set:
                              ```"attributes": [
                                  {
                                    "type": "Header",
                                    "key": "vehicle-id"
                                    "value":"$vin"
                                  }
                                ]```
                        will be valued at data map key/value: 
                                
                        {"vehicle-id: VF123456"}
    PushNotifAttributeSet:          
          description: Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a paylod key/value map enhancement or simply added to the notification event body (as set of key/value).
          type: array
          items:
            $ref: '#/components/schemas/PushNotifAttribute'
            
    CallbackAttributes:
      title: CallbackAttributes
      description: |
                    Additional attributes that will add to or replace the specific callback (pushnotif, webhook or websocket) ones when sending the monitor event.
                            
                    * Note: Union attributes set. Only one of the following: pushnotif, webhook orwebsocket should be set and it should be consistent with the callback type to wich this monitor is associated
      type: object
      properties:
        pushnotif:
          description: Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a paylod key/value map enhancement or simply added to the notification event body (as set of key/value).
          type: array
          items:
            $ref: '#/components/schemas/PushNotifAttribute'
        webhook:
          description: Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a header enhancement (such as headers can be used as an authentication parameter when posting the event) or simply added to the notification event body (as set of key/values) or finally as additional query parameters.
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        websocket:
          description: Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as a paylod key/value map enhancement or simply added to the notification event body (as set of key/value).
          type: array
          items:
            $ref: '#/components/schemas/WSAttribute'           
            
    BasicAttribute:
      allOf:
        - description: |
              Common basic attribute. Allowing to add a key/value map to a notification event when sending.
        - $ref: '#/components/schemas/Attribute'
        - properties:
              type:
                type: string
                description: |  
                 
                    
                          |type|Role|
                          |----------|-------------|
                          |Header|Will be add as callback header entry (x-###### for webhool callback or as data map key/value for push-notif).|
                          |Body|-Will be  added to event body map.|
                
                enum: [Header,Body]
    RemoteAttribute:
      allOf:
        - $ref: '#/components/schemas/BasicAttribute'
        

        - properties:
        
              value:
                oneOf:
                  - type: string
                  - type: string
                    enum: [RemoteType, RemoteStatus, RemoteLabel] 
                    description: |
                      Set of variables that will be contextually valued and used as attribute value. To reference the variable, prefix its name with the dollar sign ($)  
                      
                     
                      * example: Having a vin=VIN123456, the following attribute set:
                              ```"attributes": [
                                  {
                                    "type": "Header",
                                    "key": "X-remoteType"
                                    "value":"$remoteType"
                                  }
                                ]```
                        will be valued as http header extension: 
                                
                        *"X-remoteType: Horn"*          

    RemoteAttributeSet:          
        type: array
        description:  Additional attributes-set as key/value pairs wich will be added to the request when sending the event. It can be used as notification header enhancement (such as headers can be used as an authentication parameter when posting the event) or simply added to the notification event body (as set of key/values) or finally as additional query parameters(if supported).
        items:
            $ref: '#/components/schemas/RemoteAttribute'  
     
              
            
    MonitorAttribute:
      allOf:
        - $ref: '#/components/schemas/BasicAttribute'
        - properties:
              value:
                oneOf:
                  - type: string
                  - type: string
                    enum: [MonitorID, MonitorLabel] 
                    description: |
                      Set of variables that will be contextually valued and used as attribute value. To reference the variable, prefix its name with the dollar sign ($)  

                      * example: Having a vin=VIN123456, the following attribute set:
                              ```"attributes": [
                                  {
                                    "type": "Header",
                                    "key": "X-monitorID"
                                    "value":"$vin"
                                  }
                                ]```
                        will be valued as http header extension: 
                                
                        *"X-monitorID: 0123456"* 
    MonitorAttributeSet:          
        type: array
        description:  Additional and specific monitor attributes-set as key/value pairs wich will be added to the remote request when sending the event. Attributes will be added in addition to the basic attributes (from callback). 
        items:
            $ref: '#/components/schemas/MonitorAttribute'  
 
                        
    PushNotif:
      title: PushNotif
      description: |
        Defines the Push-Notification callback. This kind of callback distributes event messages to the user devices (Android or iOS). This push-notification feature is based on FCM (Firebase Cloud Messaging) and supports APNs (Apple Push Notification service) and GCM (Google Cloud Messaging for Android) notification channels.
        
        An attribute set (_attributes_) entry allows you to insert any convenient data (as _message.data_ feld of FCM message) into all events sent through this callback.
        
        _**Note 1**_: Basic notification template is used across all platforms.
                    
                    ```{
                      "name":string,
                      "data":{ 
                        string:string,
                        ...
                      },
                      "notification": {
                        object (Notification)
                      },
                    "token": string
                    }```
                    
          | Fields   |            |   
          |----------|:-------------:|
          |name|The identifier of the message to send|
          |data|Arbitrary key/value payload (filled from header attribut-set of callback and event)|
          |notification|Basic notification template(will expose the body of MPH event) |  
          
          
        _**Note 2**_: During the Push-Notif Callback lifecycle, when a device has been unregistered by the OS and not by the API, the device ID will also be removed from the callback and if the Devices list is cleared then the callback is deleted as well as its associated Monitors.
      type: object
      properties:
        devices:
          description: List of user devices that will receive event messages.
          type: array
          minItems: 1
          items:
              type: string
        attributes:
          $ref: '#/components/schemas/PushNotifAttributeSet'
    Websocket:
      allOf:
          - title: Websocket
            description: |
              Defines the websocket callback. This kind of callback distributes event messages in SI to SI way.  
              * An attribute set (_attributes_) entry allows you to insert any convenient data (as _message.data_ ) into all events sent through this callback. 
              * It is strongly recommended to always use WebSocket over TLS (_secure WebSocket_) for production environment.
              * For authentication purpose, login/pwd as part of url query string can be used as equivalent to  _basic authrntication_.
              * On failure, the send of  message(s) is retried until it succeeds or retention time is exceeded.
              * Retry delay (time before retrying to send the notification) is set at 10 seconds.
              * Messages retention: data is deleted within 72 hours if not sent.
              * Batch notifying (group notification in message) is used with a size (number of item per bucket) set at 100. 
                * This batch size will be applied in the case of messages lag.
                * With batch system only event's body attributes (see callback and monitor attrbiutes) are set/or valued.
            type: object
            properties:
              target:
                $ref: '#/components/schemas/Url'
              attributes:
                $ref: '#/components/schemas/WSAttributeSet'
               
            required: 
              - target
    Webhook:
      allOf:
          - title: Webhook
            description: |
                          Defines the webhook for http notification. 
                          * On failure, the send of  message(s) is retried until it succeeds or retention time is exceeded.
                          * Retry delay (time before retrying to send the notification) is set at 10 seconds.
                          * Messages retention: data is deleted within 72 hours if not sent.
                          * Batch notifying (group notification in message) is used with a size (number of item per bucket) set at 100. 
                            * This batch size will be applied in the case of messages lag.
                            * With batch system only event's body attributes (see callback and monitor attrbiutes) are set/or valued.
                                        
            type: object
            properties:
              name:
                type: string
                description: Webhook name.
              target:
                $ref: '#/components/schemas/Url' 
              attributes:
                $ref: '#/components/schemas/AttributeSet'
            required:
              - target
              - name
            example:
              target: https://my.post.callback
              name: My_Webhook
              attributes:
                      - type: Header
                        key: X-Vehicle_Id
                        value: $vin
                
    CallbackSubscribe:
      description: Callback subscription parameters. A callback subscribe parameters is related to a user and will be used with features that require  it (monitor , remote).
      type: object
      properties:
        label:
          type: string
        type:
          allOf:
           - $ref: '#/components/schemas/SubscribeType'
           - description:  The supported types of subscription by this CB. If the field is not set then the callback will be eligible to accept both of monitor and remote features. 
        callback:
          description: The callback can only be one of the following elements (webhook, websocket or pushnotif).
          type: object
          properties: 
            pushnotif:
              $ref: '#/components/schemas/PushNotif'
            webhook:
              $ref: '#/components/schemas/Webhook'
            websocket:
              $ref: '#/components/schemas/Websocket'
         
      required: [callback]
      
    MonitorCallbackSubscribe:
          description: |
                      Monitor Callback subscription extension. 
                      * Note: At least one of the parameters must be provided.
          type: object
          properties:
            refreshEvent:
                    description:  Define the period (in sec.) between two refresh events. The refresh-events are sent when the condition of the monitor is satisfied (Trigger -> toggled true). A kind of periodic reminder.
                    type: integer
                    minimum: 60
            callbackAttributes:
              allOf:
                  - description: |
                                Additional attributes that will be add to or replace the specific callback (pushnotif, webhook or websocket) ones when sending the monitor event.
                                
                                * Note: Union attributes set. Only one of the following: pushnotif, webhook orwebsocket should be set and it should be consistent with the callback type to wich this monitor is associated
                  - $ref: '#/components/schemas/CallbackAttributes'
                  
              
    MonitorStatus:
      type: string
      enum: [Running, Paused, Failed]
      
    Monitor:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - title: Monitor
          description: Monitor state object
          type: object
          properties:
            updatedAt:
              type: string
              format: date-time      
            _links:
              type: object
              properties:
                self:
                  $ref: '#/components/schemas/Link'
              required: [self] 
            monitorId:
              $ref: '#/components/schemas/MonitorId'
            monitor:
              $ref: '#/components/schemas/MonitorParameter'
            status:
              $ref: '#/components/schemas/MonitorStatus'
          required: [status,monitorId,monitor,createdAt,updatedAt,_links]
    MonitorStatusSetter:
      title: MonitorStatusSetter
      description: MonitorStatusSetter
      required: [status]
      properties:
          status:
            type: string
            enum: [Running, Paused]
    
    MonitorParameter:
      title: MonitorParameter
      description: MonitorParameter
      properties:
            label:
              type: string
              description: Monitor label (usually its name). 
            subscribeParam:
              $ref: '#/components/schemas/MonitorCallbackSubscribe'
            attributes:
              $ref: '#/components/schemas/MonitorAttributeSet'
            extendedEventParam:
              type: array
              items:
                 enum: [vehicle.doorsState, vehicle.status, vehicle.maintenance,vehicle.position, vehicle.telemetry, vehicle.alerts, vehicle.alarm, vehicle.trip]
              description: | 
                            Allow to set extra vehicle data (defined in data model) to add to the monitor event
                            when publishing. The possible values are :
                            
                            
                            |value|description|Related model |
                            |----------|:-------------|------:|
                            |vehicle.doorsState|Latest known door state (timestamped) before the eventDate|DoorState|
                            |vehicle.status|Latest known vehicle status (timestamped) before the eventDate|Status|
                            |vehicle.maintenance|Latest known maintenance(timestamped) before the eventDate|Maintenance|
                            |vehicle.position|Last vehicle position (timestamped) before the eventDate|Position|
                            |vehicle.telemetry${.TelemetryEnum} |Latest known telemetry (timestamped) before the eventDate filtered with type|Telemetry
                            |vehicle.alerts|List of active alerts at the eventDate|Alert|
                            |vehicle.alarm|Latest Vehicle alarm status and trigger|Alarm|
                            |vehicle.trip|Trip related to the event that triggers the notification|Trip|

                            
                            * For telemetry extension:  
                              * The suffix ```${.TelemetryEnum}``` can be selected to refine with telemetry type (from the TelemetryEnum list). This value (with suffix) can be selected **_several times_** to included suitable telemetry messages with the extention.
                              * Using ```vehicle.telemetry``` without suffix means to include all available telemetries. 
                            * The set of data will then correspond to the union of extensions used in the request.

            triggerParam:
              description: Monitor trigger-param that allows to compound triggers by applying a boolean expression to evaluate them.
                             
                # **Note**: To be compliant with the previous spec version (retro compatibility) this parameter continues to expose ```timeZoneTriggers``` and ```dataTriggers```
                # with only ```AND``` relationship. It is not possible the compound the old and the new triggers *style* (and will result with ```HTTP-400``` error)
              properties:
                          triggers:
                            description: |
                              Compound monitor triggers (will be evaluated using boolean expresion :```booExp```). At least, ```one``` trigger should be provided and at  most, ```five``` items are accepted.
                            type: array
                            minItems: 1
                            maxItems: 5
                            items:
                                $ref: '#/components/schemas/MonitorTrigger'      
                          boolExp:
                              type: string
                              description: |
                                A boolean expression that allow defining a logical relationship between triggers. Used Operands with this expression should be the names of the defined triggers. 
                                 
                                  _Note:_ Always ```true``` or Always```false``` expression are prohibited and will result with an http 400 error response.
                                  
                                  
                                Grammar:
                                ```
                                exp ::= exp '&' exp
                                       | exp '|' exp
                                       | (exp)
                                       | !exp
                                ```
                                
                                * **example**: having two-zone trigger (two towns) named z1 an z2, one time-trigger (8h00 to 20h00) named t1 and finally three data triggerd named as follow: f(fuel), a(autonomy) , o(odometer).
                                  
                                  we can have a boolean expression such as: : ``` ((z1 & t1) | (z2 & !t1) | (f & z1) | (a & (z1|t))  | (o & (z1 | z2))) ```
                              example :
                                ((z1 & t1) | (z2 & !t1) | (f & z1) | (a & (z1|t))  | (o & (z1 | z2)))
              required: [triggers,boolExp]
      required: [triggerParam,label]
    
    MonitorRef: 
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - type: object
          description: Monitor creation reference returned when posting a new monitor.
          required: [monitorId, status, createdAt, updatedAt]
          properties:
                updatedAt:
                  type: string
                  format: date-time
                _links:
                    type: object
                    properties:
                      monitor:
                        $ref: '#/components/schemas/Link'
                monitorId:
                  $ref: '#/components/schemas/MonitorId'
                status:
                  $ref: '#/components/schemas/MonitorStatus'
    
    MonitorTrigger:
      title: MonitorTrigger  
      description: Monitor trigger.```Only one```of *Zone, Time or Data* is supported at a time. Otherwise it would cause a bad request response.  
      properties:
        name: 
          description: 'The trigger name must be uniq and respect the following pattern'
          pattern: "\"[a-zA-Z]+[.-_]?[0-9]*\""
          type: string
        zone: 
             $ref: '#/components/schemas/ZoneTrigger'
        time: 
             $ref: '#/components/schemas/TimeTrigger'
        data: 
             $ref: '#/components/schemas/DataTrigger'     
      required: [name]  
                 
    ZoneTrigger:
      title: ZoneTrigger
      description: Zone Alert parameter object
      properties:
            transition:
              description: Zone monitoring type ('In' for monitoring entering zone and 'Out' for monitoring leaving zone),
              type: string
              enum:
                - In
                - Out
            place:
                    description: Circle zone is compound of a center point and a radius.
                    required:
                      - center
                      - radius
                    properties:
                      radius:
                        description: Circle radius (expressed in km)
                        type: integer
                      center:
                        type: object
                        properties:
                          longitude:
                            type: number
                            format: double
                          latitude:
                            type: number
                            format: double
                        required: [longitude, latitude]
      required: [place, transition]
      example: 
                        transition: Out
                        place:
                          radius: 20
                          center:
                            longitude: 2.333333
                            latitude:  48.866667
    
    TimeTrigger:
      title: TimeTrigger
      description: Temporal monitor for triggering vehicle moving event within a time interval.
      required: [times]
      properties:
            times:
              type: array
              items:
                $ref: '#/components/schemas/TimeTriggerEntry'
            timeZone: 
              type: string
              pattern: \w?/\w?
              default: Europe/Paris
              description: The standard time [zone code](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) of the region where to apply this time trigger monitor. 
                  This allows to adapt this trigger to the time change according to local (region/country) criteria/rules.
              example: Europe/Paris
    
            
    DataTrigger:
      title: DataTrigger
      description: A monitor for triggering the vehicle data change event.
      properties:
        data:
          description: | 
            The left operand of the trigger function. The following Table details for each operand data its type, the supported operator and the possibly retruned value:
            
            |**Data**|**Type**|**Op**|**Value**|
            |---|---| ---:| ---:|
            | vehicle.alert | List of value | onChange (at least one)/includedIn/equalsTo | AlertMsgEnum |
            | vehicle.odometer | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.powertrain.status |Enum(powertrain.status) | equalsTo / onChange/includedIn | Value |
            | vehicle.engines.thermic.oil.temp | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.energy.electric.level | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.energy.electric.autonomy | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.energy.fuel.level | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.energy.fuel.autonomy | Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.autonomy (global) | Integer | equalsTo/greaterThan/lowerThan | Value |
            | vehicle.energy.charging.status | Enum(ChargingStatusEnum) | onChange/equalsTo/includedIn | Value |
            | vehicle.energy.charging.plugged | Boolean | onChange/equalsTo | Value |
            | vehicle.energy.charging.type | Enum(ChargingTypeEnum) | onChange/equalsTo | Value |
            | vehicle.doorsState.lockedState | N/A | onChange | Value |
            | vehicle.doorsState.opening | N/A | onChange | Value |
            | vehicle.kinetic.moving| Boolean | onChange/equalsTo | Value (true/false) |
            | vehicle.kinetic.speed | Number | equalsTo/greaterThan/lowerThan | Value |
            | vehicle.trip.start| Literal | onChange| Value(IDTRIP) |
            | vehicle.trip.stop| Literal | onChange| Value(IDTRIP) |
            | vehicle.trip.duration| Integer | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.trip.distance| Number | equalsTo/greaterThan/lowerThan| Value |
            | vehicle.trip.state| List of value |includedIn| TripStateEnumArray |          
            | vehicle.safety.beltWarning | Enum(beltWarning) | onChange/equalsTo | Value |
            | environment.air.temp | Number | equalsTo/greaterThan/lowerThan | Value |
            | privacy.state | Enum(Privacy) | equalsTo/onChange/includedIn | Value |
            | vehicle.drivingBehavior.mode | Enum(drivingBehavior.mode) | equalsTo / onChange/includedIn | Value |
            | vehicle.safety.autoECallTriggering | Enum(safety.autoECallTriggering) | equalsTo / onChange/includedIn | Value |
            | vehicle.preconditioning.airConditioning | N/A| onChange | Value |
            | vehicle.alarm.trigger.type | Enum(trigger.type)| onChange/equalsTo/includedIn  | Value |
            | vehicle.alarm.status.activation | Enum(status.activation)| onChange/equalsTo  | Value |
            
                        
            The right operand  (value) argument depends on the type of operation (OP) as following:
              
              * onChange: no value because we are monitoring the change between two states (before and after).
              * includedIn: value must be an array of size> = 1
              * equalsTo, greaterThan and lowerThan: the value must be an array of size = 1.
          type: string
          enum:
            - vehicle.alert
            - vehicle.odometer
            - vehicle.powertrain.status
            - vehicle.engines.thermic.oil.temp
            - vehicle.energy.electric.level
            - vehicle.energy.electric.autonomy
            - vehicle.energy.fuel.level
            - vehicle.energy.fuel.autonomy
            - vehicle.autonomy
            - vehicle.energy.charging.status
            - vehicle.energy.charging.plugged
            - vehicle.energy.charging.type
            - vehicle.doorsState.lockedState
            - vehicle.doorsState.opening
            - vehicle.kinetic.moving
            - vehicle.kinetic.speed
            - vehicle.trip.start
            - vehicle.trip.stop
            - vehicle.trip.duration
            - vehicle.trip.distance
            - vehicle.trip.state
            - vehicle.safety.beltWarning
            - environment.air.temp
            - privacy.state
            - vehicle.drivingBehavior.mode
            - vehicle.safety.autoECallTriggering
            - vehicle.preconditioning.airConditioning
            - vehicle.alarm.trigger.type
            - vehicle.alarm.status.activation
        op:
            description: The operator of the trigger function.                          
            type: string
            enum: [equalsTo, greaterThan, lowerThan, includedIn, onChange]
        value:
            description: |
              The right operand of the trigger function. It can be a uniq ```value``` or a list of value ```values```. The choice of one or the other depends on ```OP```  which in the case of ```includedIn``` must be a list.
                * _Disclaimer_: If the op field is not set to ```includeIn``` then only the first item will be used.
            type: array
            items:
              type: string
        previous: 
          description: |
            The previous trigger state represents the initial state of the monitored data that allow its trigger to fire.  Only data that is in the following list is allowed. A 'previous data state' defined here must match with the defined one in the trigger data.
                        
            |**Previous Data**|**Type**|**Eligible Op**|**Previous Value**|**oAuth2 scope**|
            |---|---| ---:| ---:|---:|
            |vehicle.alert|List of value|includedIn/equalsTo| Value (AlertMsgEnum)|alert|
            |vehicle.engines.running|Boolean|equalsTo| Value (true/false)|telemetry:vehicle:engines|
            |vehicle.energy.charging.status|Enum(ChargingStatusEnum)|includedIn/equalsTo| Value(ChargingStatusEnum)|telemetry:vehicle:energies|
            |vehicle.energy.charging.plugged|Boolean|equalsTo| Value (true/false)|telemetry:vehicle:energies|
            |vehicle.kinetic.moving|Boolean|equalsTo| Value (true/false)|telemetry:vehicle:kinetic|
            |vehicle.safety.beltWarning|Enum(beltWarning)|includedIn/equalsTo| Value(Enum(beltWarning))|telemetry:vehicle:safety|
            |vehicle.safety.autoECallTriggering| Enum(safety.autoECallTriggering)|equalsTo/includedIn| Value(enum)  |telemetry:vehicle:safety| 
            |privacy.state|Enum(Privacy)|equalsTo/includedIn| Value(Enum(Privacy))|telemetry:privacy|
            |vehicle.drivingBehavior.mode|Enum(drivingBehavior.mode)|equalsTo/includedIn| Value(Enum(drivingBehavior.mode))|telemetry:vehicle:drivingBehavior|                           

            _Note:_  
              * This state will only be interpreted on the first triggering of the trigger. For the triggering due to "refresh" mode, this previous state will not be taken into account.
              * If the trigger predicate backs to 'false' then the previous state becomes again an initial necessary condition  to trigger the monitored data.
              
            The  value  depends on the type of Eligible OP  as following (if a :
              
              * includedIn: value must be an array of size> = 1
              * equalsTo: the value must be an array of size = 1.
          type: object
          properties: 
            value:
                description: The trigger previous state data literal value.
                type: array
                items:
                  type: string
            op:
              description: The operator of the previous trigger function.                          
              type: string
              enum: [equalsTo, includedIn]
          required: [value, op]
      required: [data,op]
      example:
        data: vehicle.energy.electric.level
        op: greaterThan
        value: ["75"]

    Monitors:
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                monitors:
                  type: array
                  items:
                    $ref: '#/components/schemas/Monitor'
    
    RemoteType:
          type: string
          enum: 
            - ThermalPreconditioning
            - ElectricBatteryChargingRequest
            - Horn
            - Doors
            - Lights
            - WakeUp
            - Navigation
  
    CallbackType:
          type: string
          enum: 
            - Remote
            - Monitor
    
    SubscribeType:
          type: array
          items:
            type: string
            enum: 
              - Monitor
              - Remote
    RemoteTypes:
          type: array
          items:
            $ref: '#/components/schemas/RemoteType'
    CallbackTypes:
          type: array
          items:
            $ref: '#/components/schemas/CallbackType'        
        
    RemoteCharging:
                  type: object                 
                  description: | 
                    Remote electric battery charging action. 
                    - ```preferences``` cannot be used in the same remote than ```schedule``` and/or ```immediate```
                  properties:
                    nextDelayedTime:
                      deprecated: true 
                      description: (!Depricated; use schedule instead)  Timestamp (as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)) of the next battery charging time.
                      type: string
                    schedule:
                      type: object
                      description: | 
                          Charge scheduling: only one of the three modes, ```programs```, ```nextDelayedTime/immediate```, or ```chargingEndTime/chargingEndTimeEnabled```, should be provided.
                          * ```chargingEndTimeEnabled ```and ```chargingEndTime``` Can be used together to set the end time.
                          * ```nextDelayedTime``` and ```immediate``` cannot be used together and are mutually exclusive. Mixing them will result in an error (HTTP 400).
                          Here are the possible combinations of start and end times with their respective settings: immediate start and end time enable toggle.
                          * ```nextDelayedTime``` and ```immediate```
                              | <b>nextDelayedTime</b> | <b> immediate</b> |<b> allowed</b> |
                              | :------------------: | :-------------------: | :-------------------: |
                              | set |not set|yes | 
                              | set |set to true/false|no |                               
                              | not set |set to true/false |yes |                               
                         
                          * ```chargingEndTime``` and ```chargingEndTimeEnabled```
                              | <b>chargingEndTime</b> | <b> chargingEndTimeEnabled</b> |<b> allowed</b> |
                              | :------------------: | :-------------------: | :-------------------: |
                              | set |not set|yes | 
                              | set |set to true / false|yes |                               
                              | not set |set to true/false  |Yes, if the chargingEndTime has been set before; otherwise, it will raise an error (HTTP 400)|   
                          * General rule: An empty schedule object will result in an error (HTTP 400).
                      properties:
                        nextDelayedTime:
                          type: string                        
                          description:  Timestamp (as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)) of the next battery charging time.
                        immediate:
                          type: boolean
                          description :  Determines if the charging will start immediately(```True```) or not.
                          example : true
                        chargingEndTime:
                          type: string                        
                          description:  Timestamp (as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)) of when the charging should end
                        chargingEndTimeEnabled:
                          type: boolean                        
                          description: Enable or disable the programmed charge end time.
                        programs:
                          description: Scheduled charging programs list.
                          type: array
                          items:
                            allOf:
                              - $ref: '#/components/schemas/BasicProgram'
                              - properties:
                                  enabled: 
                                    type: boolean
                                    description: True if the progrm is enables, foalse otherwise.
                                    
                                  end:
                                      type: string
                                      description: |
                                                    The program relative (to 00:00) end time formatted using the duration format based on [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) with the schema: P[n]Y[n]M[n]DT[n]H[n]M[n]S
                                                
                                                    _example_: 
                                                  
                                                    * PT14H30M means 14H and 30Min
                                      example : PT14H30M                              
                    immediate:
                      type: boolean
                      description :  Determines if the charging will start immediately(```true```) or not.
                    preferences: 
                      description: Set the charging preferences.
                      type: object
                      properties:
                        level: 
                          description:  Charging power level. 
                          type: string
                          example: Level1
                          enum: [Level1, Level2, Level3, Level4, Level5]
                        type:
                          description : Configure charging type preferences.
                          type : string
                          enum: [Partial , Full]
                          example: Partial
    
    RemoteLights:
                  type: object
                  description: Remote to swith on / off lights.
                  properties:
                    on:
                      type: boolean
                      description :  Swith, if ```true```, the vehicle lights ON  or OFF (otherwise).   
                    #duration:
                      #description : |
                        #The duration of the lighting if switched on (expressed using  [ISO-8601 Duration spec](https://en.wikipedia.org/wiki/ISO_8601#Durations))
                          #* minimum: ```PT1S```  _1 sec_.
                          #* maximum: ```PT2M0S```   _120 sec_.
                      #type: string
                      #default: PT10S
                      #example: PT20S
                  required: [on]
    
    RemoteWakeUp:
                  type: object
                  description: Remote to wake up a vehicle (so it can update its data).
                  properties:
                    action:
                      type: string
                      default: WakeUp
                      example: WakeUp
                      items:
                        enum: [WakeUp]

    RemoteNavigation:
                  type: object
                  description: A remote to share GPS positions with the vehicle so it can navigate through those positions by driving from start (1st) to end (last) position. It can include only 9 points + the destination.
                  properties:
                    driverApproval:
                        description: Whether sharing position with vehicle requires driver approval or not.
                        default: false
                        type: boolean
                        deprecated: true
                    positions:
                        type: array
                        minItems: 1
                        maxItems: 10
                        items:
                            $ref: '#/components/schemas/Point'   
                  required: [positions]
                    
    RemotePreconditioning:
      type: object
      description: Remote preconditioning the vehicle.
      properties:
        airConditioning:
          description: At least one of the parameters must be provided.
          type : object
          properties:
            immediate:
              type: boolean
              default: false
              description :  Determines whether air conditioning will start immediately or not independently if scheduled ```programs``` are set or not. Set to "false" by default.
              example : false
            programs:
              description : List of air conditioning programs to schedule on vehicle.
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/Program'
                  - description: | 
                        Air conditioning program to schedule on vehicle. ```Be aware about the action type (see below)```.
                        
                          * _Note_:The requirement to have fields provided or not depends on the value of the fields "actionsType".indeed, fields are provided when:
                          
                              |<b>actionsType</b>|<b> Mandatories</b> |
                              | :------------------: | :-------------------: |
                              |- Set |<p>slot, enabled, occurence, start</p> | 
                              |- Delete |slot |
                           
                          ## *The field  ```actionsType```is not mandatory and will be set to ```'Set'``` value if not provided.*
                  - properties: 
                      slot:
                        type: integer
                        description: This program number. Can only be used ONE time in the same preconditioning list.
                        minimum: 1
                        maximum: 4
                      enabled:
                          type: boolean
                          description: > 
                                    Determines whether this program is enabled or not.
                      actionsType:
                        description: | 
                            Action type to apply for this program:
                            
                            * Delete: Delete this air conditioning program entry. Need only the slot number of the program to remove.  
                            * Set: Create a new programe o update it if existing. Need to provide all field correctly set.
                        type: string
                        enum: [Delete, Set]
                        default: Set
                        example: Set
      required : [airConditioning]
          
    RemoteDoorsState:
      type: object
      description: |
        Remote vehicle door (lock/unlock) state.
        _Disclaimer_ : "Forced" parameter is only applicable to lock the doors and is now deprecated because not applicable to all vehicles. It will be ignored to unlock the doors if set.
        Some additionnal details will be added in the callback when this parameter is considered.
      properties:
        state:
              type: string
              enum: [Unlocked, Locked]
              example : Unlocked
        forced:
              deprecated: true
              type: boolean
              example : true
              
      required: [state]
          
    RemoteHorn:
      type: object
      description: Remote vehicle horn activation.
      properties:
      #      number:
      #        type: integer
      #        description : Number of vehicle horn activations.
      #        default: 1
      #        minimum: 1
      #        maximum: 5
            state:
              type: string
              description : Activate or unactivate this remote horn.
              enum: [Activated,Unactivated]
              example : Activated
      required: [state]
    
    Remote:
      type: object
      description: Remote vehicle activation. ```Only one action``` (horn, precond, door...) is supported at a time.
      properties:
        label:
          type: string
        attributes:
              $ref: '#/components/schemas/RemoteAttributeSet'
        callbackAttributes:
          allOf:
              - description: |
                            Additional attributes that will be add to or replace the specific callback (pushnotif, webhook or websocket) ones when sending the remote event.
                            
                            * Note: Union attributes set. Only one of the following: pushnotif, webhook orwebsocket should be set and it should be consistent with the callback type to wich this remote is associated
              - $ref: '#/components/schemas/CallbackAttributes'
        preconditioning:
          $ref: '#/components/schemas/RemotePreconditioning'
        door:
          $ref: '#/components/schemas/RemoteDoorsState'
        horn:
          $ref: '#/components/schemas/RemoteHorn'
        charging:
          $ref: '#/components/schemas/RemoteCharging'
        lights: 
          $ref: '#/components/schemas/RemoteLights'
        wakeUp: 
          $ref: '#/components/schemas/RemoteWakeUp'
        navigation: 
          $ref: '#/components/schemas/RemoteNavigation'
        
    CallbackRef: 
      type: object
      description: Callback reference returned when posting/getting a callback.
      properties:
            _links:
                type: object
                properties:
                  callback:
                    $ref: '#/components/schemas/Link'
            callbackId:
              $ref: '#/components/schemas/CallbackId'
            status:
              $ref: '#/components/schemas/CallbackStatus'          
    
    CallbackStatus:
      type: string
      enum: [Running, Paused, Failed]
      example : Running
      
    RemoteActionStatus:
      type: string
      enum: [Accepted, Failed, Success, AlreadyDone, WakingUpVehicle, CheckingVehicle, SentToVehicle, VehicleBatteryChargeTooLow,TooManyWakeUpsOverMonth]
      example : Accepted
    RemoteRef: 
      type: object
      properties:
            remoteActionId:
              $ref: '#/components/schemas/RemoteActionId'
            status:
              $ref: '#/components/schemas/RemoteActionStatus'
            type:
                  $ref: '#/components/schemas/RemoteType'
    
    RemotePostResponse: 
      type: object
      description: Remote action reference returned when posting a remote action.
      properties:
            _links:
                type: object
                properties:
                  callback:
                    $ref: '#/components/schemas/Link'
                  remote:
                    $ref: '#/components/schemas/Link'
            remoteActionId:
              $ref: '#/components/schemas/RemoteActionId'
            type:
               $ref: '#/components/schemas/RemoteType'           
    
    RemoteAction: 
      allOf:
        - $ref: '#/components/schemas/RemoteRef'
        - description: Remote action with its current state.
          properties:
                _links:
                  type: object
                  properties:
                    callback:
                      $ref: '#/components/schemas/Link'
                    self:
                      $ref: '#/components/schemas/Link'
                  required : [self]
                remoteActionId:
                  $ref: '#/components/schemas/RemoteActionId'
                remote:
                  $ref: '#/components/schemas/Remote'
                status:
                  $ref: '#/components/schemas/RemoteActionStatus'
                failureCause:   
                  $ref: '#/components/schemas/RemoteFailedEventStatus'
                feedbackDetail:
                  $ref: '#/components/schemas/RemoteEventFeedbackDetail'
          required : [_links]
    
    RemoteActions:
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                remoteActions:
                  type: array
                  items:
                    $ref: '#/components/schemas/RemoteAction'
    
    CallbackId:
      type: string
      description: Uniq callback ID returned when the callback was subscribed (created) succefuly.
    
    RemoteActionId:
      type: string
      description: The uniq remote action  ID returned when the remote action was posted and accepted.
    
    UserCallback:
      description:  Callback state.
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
          required: [self]
           
        label:
          type: string
        id:
          $ref: '#/components/schemas/CallbackId'
        subscribe:
          $ref: '#/components/schemas/CallbackSubscribe'
        status:
          $ref: '#/components/schemas/CallbackStatus'
      required: [status,id,subscribe, _links]
    
    UserCallbacks:
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                callbacks:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserCallback'
    
    CallbacksStatusSetter:
      title: CallbacksStatusSetter
      description: User Callback Status setter used to change the state from running to paused and vice versa. 
      required: [status]
      properties:
          status:
            type: string
            enum: [Running, Paused]
            example : Running
 
    RemoteFailedEventStatus:
      description: | 
        The failure cause for event with failed status. This field is filled only is failure state. 
      type: string    
      enum: 
            - GeneralError
            - VehicleError
            - WrongCommand
            - VehicleConnectionTimeout
            - MissingRights
            - NotPossibleDueToVehicleBatteryLevel
            - NotPossibleDueToVehiclePrivacyLevel
            - TooManyWakeUpsOverMonth
            - TooManyRequestInShortTime
            - SameActionInProgress
            - NotPossibleDueToVehicleStolenState
            - VehicleInUse
            - TooManyRequestSent 
            - DoorsOpen
            - VehicleErrorOrCidInside
            - CidInside
            - ExternalChargingSystemError
            - VehicleChargingSystemError
            - VehicleIsNotLocked
            - CanceledByDriver
    
    RemoteEventFeedbackDetail:
      description: | 
        Additionnal detail in case of success on some specific behavior :
        
        |Feature|Description|Behavior|
        |----------|:-------------|------:|
        |Lock Doors|Send a lock doors by force|NoCIDBlacklisted if lock is OK but IML not blacklisted, CIDBlacklisted is when the doors are locked and the IML is well blacklisted|
      type: string
      enum:
            - NoCIDBlacklisted
            - CIDBlacklisted        

    BaseAlarmTrigger:
      type: object
      title: Vehicle Alarm Trigger
      description: Describe a vehicle alarm trigger.
      properties:
          type: 
            description: Define the vehicle break-in type.
            type: string
            enum:
                - NoBreakIn
                - FrontRightDoorBreakIn
                - FrontLeftDoorBreakIn
                - RearRightFrontDoorBreakIn
                - RearLeftFrontDoorBreakIn
                - HoodDoorBreakIn
                - TrunkDoorBreakIn
                - BackliteDoorBreakIn
                - RoofBreakIn
                - VolumetricBreakIn
                - VehicleLifting
                - ElectricalsystemBreakIn
                - KeyLearning
                - UnauthenticatedStartup
          position:
            allOf:
                - description: The position (last vehicle known one) where the alarm triggered.
                - $ref: '#/components/schemas/Position'
          startAt:
            description: Time when the alarm triggering started.
            type: string
            format: date-time
      required: [type, startAt]
      
      
    BaseAlarmStatus:
      type: object
      title: Vehicle Alarm Status
      description: Describe a vehicle alarm status.
      properties:
          activation: 
            description: Define whether the vehicle alarm is active or not.
            type: string
            enum: [Inactive, Active]
            example : Active
      required: [activation]
        
    BaseAlarm:
      type: object
      title: VehicleAlarm
      description: Describe a vehicle alarm status and trigger.
      properties:
        status:
          $ref: '#/components/schemas/BaseAlarmStatus'
        trigger:
          $ref: '#/components/schemas/BaseAlarmTrigger'
      
    AlarmTrigger:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/BaseAlarmTrigger'
        - title: Vehicle Alarm Trigger
        - required: [type, startAt, createdAt]
        
    AlarmStatus:
      allOf:
        - $ref: '#/components/schemas/CreatedAtField'
        - $ref: '#/components/schemas/BaseAlarmStatus'
        - title: Vehicle Alarm Status
        - required: [activation, createdAt]
        
    Alarm:
      type: object
      title: Vehicle Alarm
      description: Describes the vehicle alarm status or trigger. Only one is present.
      properties:
        trigger:
            $ref: '#/components/schemas/AlarmTrigger'
        status:
            $ref: '#/components/schemas/AlarmStatus'
    
    VehicleStatusAlarm:
      allOf:
        - $ref: '#/components/schemas/Alarm'
        - description: Describes the current vehicle alarm status and the latest (if available) trigger.
    
    AlarmDetails :
      allOf:
        - properties:
            id : 
              type: string
        - $ref: '#/components/schemas/Alarm'
        - required : [id]

    Alarms:
      title: Alarm array
      allOf:
        - $ref: '#/components/schemas/CollectionResult'
        - properties:
            _embedded:
              type: object
              properties:
                alarms:
                  type: array
                  items:
                    $ref: '#/components/schemas/AlarmDetails'        
    ######
    ####################
        
  parameters:

    genericId:
      name: ''
      required: true
      in: path
      schema:
        type: string
        #    apiClientId:
        #      name: client_id
        #      description: The client ID related to the API User account.
        #      in: query
        #      required: true
        #      schema:
        #        type: string
        #        pattern: '([0-9a-fA-F]|-|_)*'
    alertId:
      name: aid
      in: path
      description: id of the alert.
      required: true
      schema:
        type: string
    alarmId:
      name: aid
      in: path
      description: id of the alamr.
      required: true
      schema:
        type: string
    collisionId:
      name: cid
      in: path
      description: Results will only contain the Collision related to this Collision *id*.
      required: true
      schema:
        type: string
    vehicleId:
      name: id
      in: path
      description: Results will only be related to this Vehicle *id*.
      required: true
      schema:
        type: string
    tripId:
      name: tid
      in: path
      required: true
      description: the *id* of Trip
      schema:
        type: string
    vinPrefix:
      name: vinPrefix
      in: query
      description: Allows filtering on VINs that start with the same prefix.
      schema:
        type: string 
    country:
      name: country
      in: query
      description: Result will adapt information according to requested country (only available for specific countries). It is as defined in ISO 3166-1 alpha-2
      schema:
        $ref: '#/components/schemas/CountryEnum'
    locale:
      name: locale
      in: query
      description: Locale is used for rendering text, correctly displaying regional monetary values, time and date formats. Respect REGEX \w(-\w)?
      required: false
      schema:
        type: string
    timestamps:
      name: timestamps
      in: query
      description: |
          Array of  **"timestamp"** ranges. Results will contain results whose
          timestamps are included in those date-time ranges (see **timestamp**
          data  model).**"timestamp"** items should be expressed as in
          '[RFC3339](https://www.ietf.org/rfc/rfc3339.txt)'. Each element of the array 
          expresses a time range (with the pattern ```\w?/\w?``` or ```R\d?/w/w(/w)?```) 
          which is the period between two or more times. The range can be expressed by tw
          o times Points (start and end *Timestamp*s), by a start
          *Timestamp* Point and a *Duration* or as a repeating interval. All of them  should be expressed using the [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) and the interval format
          is based on [ISO8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)
          - 'T1/T2' interval time from low limit T1 to hight T2
          - 'T1/D' interval time from low limit T1 with duration = D ( T2=T1+D)
          - 'T/' endless range, known start Timestamp but no end Timestamp. The current time  will be used as the high time limit.
          - '/T' startless range, known end date but no start date. No lower limit will be used to retrieve results.
          - Rn/T/D/[d]  repeat the interval of D **n** times starting at T using **d** (extension of the standard and not mandatory) as range duration. The default (duration) value of d is 24 H
          - R/T/D/[d] unbounded number of repetitions starting at T using **d** (extension of the standard and not mandatory) as range duration. The default (duration) value of d is 24 H.
          - T is a timestamp and D is a duration  as defined in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt).
          - Examples:
            - 2018-01-01T09:00:00+01:00/2018-01-01T12:00:00+01:00* known low and hight limits.
            - *2018-01-03T12:00:00+01:00/P3Y6M4DT12H30M5S*  known low limit, hight limit = start + duration.
            - *2018-01-03T12:00:00+01:00/*  known low limit, hight limit = current time.
            - *R5/2018-01-03T12:00:00Z/P6H/P2H* repeate duration 6H wiht interval period of 2H for 5 times starting at 2018-01-03T12:00:00Z.
      required: false
      schema:
        type: array
        minItems: 1
        maxItems: 10
        items:
          type: string
          pattern: \w?/\w?

         # $ref: '#/components/schemas/TimeRange'
    
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 60
        minimum: 1
        maximum: 60
      required: false
      description: >-
        The maximum number of results (for a collection results response) to
        return per page. When not set, at most 60 results will be returned. 
        The range for this parameter is [1...60]
    
    pageSizeHighFrequency:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 2000
        default: 60
      required: false
      description: >-
        The maximum number of results (for a collection results response) to
        return per page for high frequency data upload. When not set, at most 60 results will be returned. 
        The range for this parameter is [1...2000]
         
    pageToken:
      name: pageToken
      in: query
      schema:
        type: string
      required: false
      description: >-
        Start-Page marker, this token is used (by the backend) for continuing serving from the previous results page to the next one. (_Disclaimer_:  **It is built and used only by the server**).
    
    indexRange:
      name: indexRange
      in: query
      schema:
        $ref: '#/components/schemas/Range'
      required: false
      description: >
        Results indexes will be included in this range. this range is used to express the first (offset) and the last results
                  index  to retrieve. With the respect to the regex pattern ```\d+(-\d*)?```,
                  the start of  range is mandatory ( 0 for default).
          
          
        *Example:*
          
          
                  *  '0-9'  : start=0, end=9    ==> offset=0 and number of items=10
          
          
                  * '5-'    : start =5, no end  ==> start at 5th to the end results.
          
          default: 0-

          example: 0-, 0-5
           
    alarmType:
      name: type
      in: query
      description:  Results will only contain Alarm messages of this type.  If no filtering type is selected then all alarms will be taken .
      required: false
      schema:
        $ref: '#/components/schemas/AlarmTypeEnum'
    
    telemetryType:
      name: type
      in: query
      description: >-
        Results will only contain Telemetry messages of this kind. You can add
        more than one message type. By default, if no type is selected then all telemetries will be taken ```(the number of elements in this array must be between 1 and 15)```.
      required: false
      schema:
        $ref: '#/components/schemas/TelemetryEnum'
    
    telemetryExtension:
      name: extension
      in: query
      description: >-
        Additional data set that will be included in embedded field```(the number of elements in this array must be between 1 and 2)```.
      required: false
      schema:
        $ref: '#/components/schemas/TelemetryExtensionType'
    vehicleExtension:
      name: extension
      in: query
      description: >-
        Additional data set that will be included in embedded field```(the number of elements in this array must be between 1 and 2)```.
      required: false
      schema:
        $ref: '#/components/schemas/VehicleExtensionType'    
    
    tolerence:
      name: tolerance
      description: >
          Tolerance factor is expressed in length KM unit and is used to simplify path by reducing the total number of points by is using Douglas-Peucker algorithme to find a similar curve with fewer points (find more info here: [Ramer_Douglas_Peucker_algorithm](https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm#Algorithm) ).
           
      in: query
      schema:
        type: number
        format: float

    monitorId:
      name: mid
      in: path
      description: id of the monitor.
      required: true
      schema:
        type: string
        
    remoteType:
      name: types
      in: query
      description: Results will contain only the Remote-Callbacks of these types. _If not specified then the whole callbacks are retrieved_.
      required: false
      schema:
        $ref: '#/components/schemas/RemoteTypes'    

    callbackType:
      name: types
      in: query
      description: Results will contain only the Callbacks of these types. _If not specified then the whole callbacks are retrieved_.
      required: false
      schema:
        $ref: '#/components/schemas/CallbackTypes'


    callbackId:
      name: cbid
      description: The callback ID.
      in: path
      required: true
      schema:
        type: string
        pattern: '([0-9a-fA-F]|-|_)*'
        
    remoteId:
      name: rid
      description: The remote action ID.
      in: path
      required: true
      schema:
        type: string
        pattern: '([0-9a-fA-F]|-|_)*'
    tripDuration:
      name: duration
      in: query
      schema:
        $ref: '#/components/schemas/Range'
      required: false
      description: >
        Trip duration validity interval. It allows to  define the min or max duration of a trip. **Unit = sec**
          
        *Example:*
          
                  * 10-3600: Trip with duration between 10 sec and 1 hour.
          
                  * 20-: Trip with duration greater than 20 sec.
          
          default: 0-
    tripDistance:
      name: distance
      in: query
      schema:
        $ref: '#/components/schemas/Range'
      required: false
      description: >
        Trip distance  validity interval. It allows to  define the min or max duration of a trip.  
        
        **Unit = Km** and format : float (only one digit after the decimal point is aceepted for the interval bounds).
          
        *Example:*
        
                  * 1-150: Trip with distance between 1 Km and 150 km .
          
                  * 0.1-: Trip with distance  greater than 100 m.
          
          default: 0-  
          
    tripState:
     description:  >
      Allow to filter for Trips with defined states. Those states can be compound of : _Nominal,Unstarted, DataLacking, Unfinished_. 
      
      
      Default: All states are allowed.
     name: states
     in: query
     schema:
      $ref: '#/components/schemas/TripStateEnumArray'

  responses:
    CollisionsuccessResponse:
      description: Collision response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Collision'
    CollisionsSuccessResponse:
      description: A list of Collision
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Collisions'
    CollisionFailedResponse:
      description: Collision request error
      $ref: '#/x-fragment/general_error_fragment'
    AlertsucessResponse:
      description: Alert response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Alert'
    AlertsuccessResponses:
      description: A list of alert
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Alerts'
    AlertFailedResponse:
      description: Alert request error
      $ref: '#/x-fragment/general_error_fragment'

    AlarmSucessResponse:
      description: Alarm response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/AlarmDetails'
    AlarmSuccessResponses:
      description: A list of alert
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Alarms'
            
    AlarmFailedResponse:
      description: Alarm request error
      $ref: '#/x-fragment/general_error_fragment'
    TripsucessResponse:
      description: Trip response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Trip'
    TripsSuccessResponses:
      description: List of Trip
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Trips'
    TripFailedResponse:
      description: Trip request error
      $ref: '#/x-fragment/general_error_fragment'
    TelemetrySuccessResponse:
      description: Telemetry response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Telemetries'
    TelemetryFailedResponse:
      description: Trip request error
      $ref: '#/x-fragment/general_error_fragment'

    MonitorsuccessStatusResponse:
      description: Monitor response
      content:
        application/hal+json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    $ref: '#/components/schemas/Link'
                  monitor:
                    $ref: '#/components/schemas/Link'
                 
              status:
                $ref: '#/components/schemas/MonitorStatus'        
    
    MonitorsuccessPostResponse:
      description: Monitor created or updated successfully
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/MonitorRef'        
    
    MonitorsuccessResponses:
      description: A list of Monitors
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Monitors'
    MonitorsuccessResponse:
      description: Monitor response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Monitor'            
    
    MonitorFailedResponse:
      description: Monitor request error
      $ref: '#/x-fragment/general_error_fragment'
        #######  R E M O T E
    UserCallbacksuccessStatusResponse:
      description: Monitor response
      content:
        application/hal+json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    $ref: '#/components/schemas/Link'
                  monitor:
                    $ref: '#/components/schemas/Link'
                 
              status:
                $ref: '#/components/schemas/CallbackStatus'        
    
    CallbackSuccessPostResponse:
      description: Callback creation or update success response
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/CallbackRef'
            
    RemoteActionsSuccessPostResponse:
      description: Remote action creation success response (accepted).
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/RemotePostResponse'
        
    CallbackSuccessResponse:
      description: A callback.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/UserCallback'
    
    CallbackSuccessResponses:
      description: A list of subsribed callback.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/UserCallbacks'
         
    RemoteActionSuccessResponses:
      description: A list of remote actions.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/RemoteActions'
            
    RemoteActionSuccessResponse:
      description: A remote action response.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/RemoteAction'
    
    #RemoteActions            
    CallbackFailedResponse:
        description:  Subscribe request error
        $ref: '#/x-fragment/general_error_fragment' 
    #RemoteActions            
    EligibilitiesFailedResponse:
        description:  Remote Actions Eligibilities request error
        $ref: '#/x-fragment/general_error_fragment' 
      
  # 2) Apply the API key globally to all operations
security:
  - api_keyAuth: []     # use the same name as under securitySchemes
    api_oauth: []
x-fragment:
  Vehicle_id_Trip_id_Telemetry_getter:
    get:
      summary: Telemetries of trip and vehicle
      tags:
        - Trips
      description: |
        Returns the set of Telemetry values that occurred for a given vehicle
        (id) and a speific Trip (tid) during the timestamp ranges and bounded by
        an index range.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:telemetry|Optional|
        |data:position|Optional|

      operationId: getTelemetryForTrip
      deprecated : true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/telemetryType'
        - $ref: '#/components/parameters/pageSizeHighFrequency'
        - $ref: '#/components/parameters/telemetryExtension'
      security:
        - api_oauth:
            - data:trip #Required
            - data:telemetry
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/TelemetrySuccessResponse'
        default:
          $ref: '#/components/responses/TelemetryFailedResponse'
  Vehicle_id_Trip_id_wayPoints_getter:
    get:
      summary: Path of trip
      tags:
        - Trips
      description: |
        Gives the Vehicle's wayPoints for a specified Trip.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:position|Required|
      operationId: getPathForTrip
      deprecated : true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/tolerence'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:trip #Required
            - data:position #Required
      responses:
        '200':
          description: Path response
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/WayPoints'
        default:
          description: wayPoints not found
  Vehicle_id_Trip_id_Collisions_id_getter:
    get:
      summary: A collsision happened for a given vehicle during a given trip
      tags:
        - Trips
      description: |
        Returns a single Collision(cid) that occurred for a given vehicle(id) during a Trip(tid).
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:collision|Required|
      operationId: getVehicleCollisionByTipById
      deprecated : true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/collisionId'
      security:
        - api_oauth:
            - data:trip #Required
            - data:collision #Required
      responses:
        '200':
          $ref: '#/components/responses/CollisionsuccessResponse'
        default:
          $ref: '#/components/responses/CollisionFailedResponse'
  Vehicle_id_Trip_id_Collisions_getter:
    get:
      summary: Collsisions happened for a given vehicle during a given trip
      tags:
        - Trips
      description: |
        Returns the set of Collisions that occurred for a given vehicle (id) and
        a speific Trip (tid) during the timestamp ranges and bounded by an index
        range.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:collision|Required|
      operationId: getVehicleCollisionsByTripId
      deprecated : true
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:trip #Required
            - data:collision #Required
      responses:
        '200':
          $ref: '#/components/responses/CollisionsSuccessResponse'
        default:
          $ref: '#/components/responses/CollisionFailedResponse'
  Vehicle_id_Trip_id_Alerts_id_getter:
    get:
      summary: Vehicle's trip specific alert.
      tags:
        - Trips
      description: |
        Returns an  alert for a given Vehicle occured during a given trip and Trip.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:alert|Required|
        |data:position|Optional|
      operationId: getVehicleTripAlertByAid
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/alertId'
      security:
        - api_oauth:
            - data:trip #Required
            - data:alert #Required
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/AlertsucessResponse'
        default:
          $ref: '#/components/responses/AlertFailedResponse'
  Vehicle_id_Trip_id_Alerts_getter:
    get:
      summary: Vehicle's trip alert list.
      tags:
        - Trips
      description: |
        Returns the alert messages for a Vehicle occurend during a trip.
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:alert|Required|
        |data:position|Optional|
      operationId: getVehicleTripAlerts
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
        - name: locale
          in: query
          description: Locale is used for rendering text, correctly displaying regional
            monetary values, time and date formats.
          required: false
          schema:
            type: string
      security:
        - api_oauth:
            - data:trip #Required
            - data:alert #Required
            - data:position 
      responses:
        '200':
          $ref: '#/components/responses/AlertsuccessResponses'
        default:
          $ref: '#/components/responses/AlertFailedResponse'
  Vehicle_id_Trip_id:
    get:
      summary: Get a vehicle trip
      tags:
        - Trips
      description: |
        This method returns the Trip that matches the Trip id (tid) for a given Vehicle (id).
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:position|Optional|
      operationId: getTripByVehicle
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/tripId'
      security:
        - api_oauth:
            - data:trip #Required
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/TripsucessResponse'
        default:
          $ref: '#/components/responses/TripFailedResponse'
  Vehicle_id_Trips:
    get:
      summary: Get a vehicle trips
      tags:
        - Trips
      description: |
        This method returns a list of all Trips that a given Vehicle has taken (including the pending one if available).
        Scope Name |Mandatory State|
        |--------|:---------:|
        |data:trip|Required|
        |data:position|Optional|
      operationId: getTripsByVehicle
      parameters:
        - $ref: '#/components/parameters/vehicleId'
        - $ref: '#/components/parameters/timestamps'
        - $ref: '#/components/parameters/tripDistance'
        - $ref: '#/components/parameters/tripDuration'
        - $ref: '#/components/parameters/tripState'
        - $ref: '#/components/parameters/indexRange'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      security:
        - api_oauth:
            - data:trip #Required
            - data:position
      responses:
        '200':
          $ref: '#/components/responses/TripsSuccessResponses'
        default:
          $ref: '#/components/responses/TripFailedResponse'

  general_error_fragment:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/xError'