{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/terminal-telematics/json-schema/terminal-telematics-vehicle-stat-log-schema.json",
  "title": "Vehicle Stat Log",
  "x-generated": "2026-11-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/terminal.openapi.json#/components/schemas/VehicleStatLog",
  "x-model-category": "time-series",
  "x-read-permission": "vehicle-stats:read",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/VehicleStatLogId"
    },
    "sourceId": {
      "$ref": "#/$defs/SourceId"
    },
    "provider": {
      "$ref": "#/$defs/ProviderCode"
    },
    "type": {
      "type": "string"
    },
    "timestamp": {
      "$ref": "#/$defs/ISODateTime"
    },
    "vehicle": {
      "$ref": "#/$defs/ExpandableVehicle",
      "description": "The vehicle this event is about."
    },
    "metadata": {
      "$ref": "#/$defs/TimeSeriesMetadata"
    },
    "raw": {
      "$ref": "#/$defs/RawDataList"
    }
  },
  "required": [
    "id",
    "provider",
    "type",
    "timestamp",
    "vehicle",
    "metadata"
  ],
  "oneOf": [
    {
      "title": "Engine State Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_state"
        },
        "state": {
          "$ref": "#/$defs/EngineState"
        }
      },
      "required": [
        "type",
        "state"
      ]
    },
    {
      "title": "Odometer Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "odometer"
        },
        "odometer": {
          "$ref": "#/$defs/DistanceInKilometers"
        }
      },
      "required": [
        "type",
        "odometer"
      ]
    },
    {
      "title": "Total Fuel Consumption Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "total_fuel_consumption"
        },
        "fuelConsumed": {
          "$ref": "#/$defs/VolumeInLiters"
        }
      },
      "required": [
        "type",
        "fuelConsumed"
      ]
    },
    {
      "title": "Fuel Level Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "fuel_level"
        },
        "fuelPercentage": {
          "$ref": "#/$defs/FuelPercentage"
        }
      },
      "required": [
        "type",
        "fuelPercentage"
      ]
    },
    {
      "title": "Engine Runtime Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_runtime"
        },
        "duration": {
          "$ref": "#/$defs/DurationInMS"
        }
      },
      "required": [
        "type",
        "duration"
      ]
    },
    {
      "title": "Engine Oil Percentage Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_oil_percentage"
        },
        "percentage": {
          "$ref": "#/$defs/Percentage"
        }
      },
      "required": [
        "type",
        "percentage"
      ]
    },
    {
      "title": "Engine Oil Pressure Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_oil_pressure"
        },
        "pressure": {
          "$ref": "#/$defs/PressureInPSI"
        }
      },
      "required": [
        "type",
        "pressure"
      ]
    },
    {
      "title": "Engine Oil Temperature Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_oil_temperature"
        },
        "temperature": {
          "$ref": "#/$defs/TemperatureInCelsius"
        }
      },
      "required": [
        "type",
        "temperature"
      ]
    },
    {
      "title": "Engine Coolant Temperature Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_coolant_temperature"
        },
        "temperature": {
          "$ref": "#/$defs/TemperatureInCelsius"
        }
      },
      "required": [
        "type",
        "temperature"
      ]
    },
    {
      "title": "Coolant Percentage Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "coolant_percentage"
        },
        "percentage": {
          "$ref": "#/$defs/Percentage"
        }
      },
      "required": [
        "type",
        "percentage"
      ]
    },
    {
      "title": "Engine RPM Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "engine_rpm"
        },
        "rpm": {
          "$ref": "#/$defs/RPM"
        }
      },
      "required": [
        "type",
        "rpm"
      ]
    },
    {
      "title": "Battery Voltage Log",
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "battery_voltage"
        },
        "voltage": {
          "$ref": "#/$defs/VoltageInVolts"
        }
      },
      "required": [
        "type",
        "voltage"
      ]
    }
  ],
  "x-description": "A point-in-time record of stats and logs for a specific vehicle.",
  "$defs": {
    "AddedAt": {
      "title": "AddedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system."
    },
    "CoreEntityMetadata": {
      "title": "CoreEntityMetadata",
      "type": "object",
      "description": "Internal metadata about the record.",
      "required": [
        "addedAt",
        "modifiedAt"
      ],
      "properties": {
        "addedAt": {
          "$ref": "#/$defs/AddedAt"
        },
        "modifiedAt": {
          "$ref": "#/$defs/ModifiedAt"
        },
        "deletedAt": {
          "$ref": "#/$defs/DeletedAt"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "visible",
            "hidden_by_exclude_list",
            "hidden_by_include_list",
            "hidden_by_status",
            "deleted"
          ],
          "description": "Visibility status of a resource. Read more about hidden records [here](https://docs.withterminal.com/guides/vehicle-driver-filtering)."
        }
      }
    },
    "DeletedAt": {
      "title": "DeletedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was deleted from Terminal. Note: this is not the date and time the record was deleted in the provider's system."
    },
    "DeviceId": {
      "title": "DeviceId",
      "type": "string",
      "format": "ulid"
    },
    "DistanceInKilometers": {
      "title": "Distance In Kilometers",
      "type": "number",
      "format": "double",
      "description": "Distance in kilometers"
    },
    "DurationInMS": {
      "title": "DurationInMS",
      "type": "integer",
      "description": "Duration in MS"
    },
    "EngineState": {
      "type": "string",
      "enum": [
        "on",
        "off",
        "idle"
      ]
    },
    "ExpandableVehicle": {
      "oneOf": [
        {
          "$ref": "#/$defs/VehicleId"
        },
        {
          "$ref": "#/$defs/ExpandedVehicle"
        }
      ]
    },
    "ExpandedVehicle": {
      "title": "Expanded Vehicle",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/VehicleId"
        },
        "sourceId": {
          "$ref": "#/$defs/SourceId"
        },
        "provider": {
          "$ref": "#/$defs/ProviderCode"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ],
          "description": "The status in the providers system"
        },
        "vin": {
          "title": "VIN",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "make": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        },
        "groups": {
          "type": "array",
          "description": "The groups the vehicle belongs to.",
          "items": {
            "$ref": "#/$defs/GroupId"
          }
        },
        "devices": {
          "type": "array",
          "description": "The devices installed in the vehicle.",
          "items": {
            "$ref": "#/$defs/DeviceId"
          }
        },
        "licensePlate": {
          "type": "object",
          "properties": {
            "state": {
              "$ref": "#/$defs/State"
            },
            "number": {
              "type": "string"
            }
          }
        },
        "fuelType": {
          "enum": [
            "gasoline",
            "diesel",
            "propane",
            "electric",
            "hybrid_gasoline",
            "hybrid_diesel",
            "biodiesel",
            "compressed_natural_gas",
            "liquefied_natural_gas",
            "ethanol",
            "hydrogen",
            "plug_in_hybrid"
          ]
        },
        "fuelEfficiency": {
          "type": "number",
          "deprecated": true,
          "description": "This field will be removed in the future as is not commonly available from providers."
        },
        "fuelTankCapacity": {
          "description": "Maximum amount of fuel vehicle can hold in liters.",
          "title": "Volume In Liters",
          "type": "number"
        },
        "createdAt": {
          "$ref": "#/$defs/SourceCreatedAt"
        },
        "updatedAt": {
          "$ref": "#/$defs/SourceUpdatedAt"
        },
        "metadata": {
          "$ref": "#/$defs/CoreEntityMetadata"
        },
        "raw": {
          "$ref": "#/$defs/RawDataList"
        }
      },
      "required": [
        "id",
        "sourceId",
        "provider",
        "status",
        "metadata"
      ],
      "x-description": "The model representing a vehicle in Terminal."
    },
    "FuelPercentage": {
      "title": "Fuel Percentage",
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "The percentage value of how much fuel is left in the tank."
    },
    "GroupId": {
      "title": "GroupId",
      "type": "string",
      "format": "ulid"
    },
    "ISODateTime": {
      "title": "ISODateTime",
      "type": "string",
      "format": "date-time",
      "description": "[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date"
    },
    "ModifiedAt": {
      "title": "ModifiedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system."
    },
    "Percentage": {
      "title": "Percentage",
      "type": "number",
      "description": "Percentage value between 0 and 100, rounded to 2 decimal places.",
      "minimum": 0,
      "maximum": 100
    },
    "PressureInPSI": {
      "title": "Pressure In PSI",
      "type": "number",
      "description": "Pressure in PSI (Pounds per Square Inch) rounded to 2 decimal places."
    },
    "ProviderCode": {
      "type": "string",
      "description": "Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers)."
    },
    "RPM": {
      "title": "RPM",
      "type": "number",
      "description": "Engine RPM (Revolutions Per Minute) rounded to 2 decimal places."
    },
    "RawData": {
      "title": "RawData",
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "schema": {
          "type": "string"
        },
        "extractedAt": {
          "type": "string"
        },
        "data": {
          "type": "object"
        }
      },
      "required": [
        "provider",
        "schema",
        "extractedAt",
        "data"
      ]
    },
    "RawDataList": {
      "title": "RawDataList",
      "type": "array",
      "items": {
        "$ref": "#/$defs/RawData"
      }
    },
    "SourceCreatedAt": {
      "title": "SourceCreatedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was created in the provider's system. This timestamp comes directly from the source system and represents when the data was originally created there. Note: not all providers expose this."
    },
    "SourceId": {
      "title": "SourceId",
      "type": "string",
      "description": "The ID used to represent the entity in the source system."
    },
    "SourceUpdatedAt": {
      "title": "SourceUpdatedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was updated in the provider's system. This timestamp comes directly from the source system and represents when the data was last updated there. Note: not all providers expose this."
    },
    "State": {
      "title": "State",
      "type": "string",
      "enum": [
        "AL",
        "AK",
        "AS",
        "AZ",
        "AR",
        "CA",
        "CO",
        "CT",
        "DE",
        "FL",
        "GA",
        "GU",
        "HI",
        "ID",
        "IL",
        "IN",
        "IA",
        "KS",
        "KY",
        "LA",
        "ME",
        "MD",
        "MA",
        "MI",
        "MN",
        "MP",
        "MS",
        "MO",
        "MT",
        "NE",
        "NV",
        "NH",
        "NJ",
        "NM",
        "NY",
        "NC",
        "ND",
        "OH",
        "OK",
        "OR",
        "PA",
        "PR",
        "RI",
        "SC",
        "SD",
        "TN",
        "TX",
        "UT",
        "VT",
        "VA",
        "WA",
        "WV",
        "WI",
        "WY",
        "VI",
        "AB",
        "BC",
        "MB",
        "NB",
        "NL",
        "NS",
        "ON",
        "PE",
        "QC",
        "SK",
        "NT",
        "NU",
        "UM",
        "YT",
        "DC"
      ],
      "description": "US State or Canadian Province"
    },
    "TemperatureInCelsius": {
      "title": "Temperature In Celsius",
      "type": "number",
      "description": "Temperature in Celsius rounded to 2 decimal places."
    },
    "TimeSeriesMetadata": {
      "title": "TimeSeriesMetadata",
      "type": "object",
      "description": "Internal metadata about the time series.",
      "required": [
        "modifiedAt"
      ],
      "properties": {
        "modifiedAt": {
          "$ref": "#/$defs/ModifiedAt"
        }
      }
    },
    "VehicleId": {
      "title": "VehicleId",
      "description": "Unique identifier for the vehicle in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^vcl_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "VehicleStatLogId": {
      "title": "VehicleStatLogId",
      "type": "string",
      "format": "ulid"
    },
    "VoltageInVolts": {
      "title": "Voltage In Volts",
      "type": "number",
      "description": "Voltage in volts rounded to 2 decimal places."
    },
    "VolumeInLiters": {
      "title": "Volume In Liters",
      "type": "number",
      "description": "Volume in liters rounded to 2 decimal places."
    }
  }
}