{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/terminal-telematics/json-schema/terminal-telematics-safety-event-schema.json",
  "title": "Safety Event",
  "x-generated": "2026-11-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/terminal.openapi.json#/components/schemas/SafetyEvent",
  "type": "object",
  "additionalProperties": false,
  "x-model-category": "time-series",
  "x-read-permission": "safety:read",
  "properties": {
    "id": {
      "$ref": "#/$defs/SafetyEventId"
    },
    "sourceId": {
      "$ref": "#/$defs/SourceId"
    },
    "provider": {
      "$ref": "#/$defs/ProviderCode"
    },
    "type": {
      "$ref": "#/$defs/SafetyEventType"
    },
    "sourceType": {
      "type": "string",
      "description": "The original event type as defined by the telematics provider's system"
    },
    "driver": {
      "$ref": "#/$defs/ExpandableDriver",
      "description": "The driver that was driving during the event."
    },
    "vehicle": {
      "$ref": "#/$defs/ExpandableVehicle",
      "description": "The vehicle that was involved in the event."
    },
    "startedAt": {
      "$ref": "#/$defs/ISODateTime"
    },
    "startLocation": {
      "$ref": "#/$defs/Coordinates"
    },
    "endedAt": {
      "$ref": "#/$defs/ISODateTime"
    },
    "endLocation": {
      "$ref": "#/$defs/Coordinates"
    },
    "stats": {
      "type": "object",
      "properties": {
        "maximumSpeed": {
          "$ref": "#/$defs/SpeedInKPH",
          "description": "Maximum speed of the vehicle in KPH, rounded to 2 decimal places."
        },
        "averageSpeed": {
          "$ref": "#/$defs/SpeedInKPH",
          "description": "Average speed of the vehicle in KPH, rounded to 2 decimal places."
        },
        "roadSpeedLimit": {
          "$ref": "#/$defs/SpeedInKPH",
          "description": "Speed limit of the road in KPH, rounded to 2 decimal places."
        },
        "gForceForwardBackward": {
          "$ref": "#/$defs/GForce",
          "description": "The acceleration/breaking force as a factor of gravity (g)."
        },
        "gForceSideToSide": {
          "$ref": "#/$defs/GForce",
          "description": "The cornering (lateral) acceleration as a factor of gravity (g)."
        },
        "heading": {
          "$ref": "#/$defs/HeadingInDegrees",
          "description": "Heading of the vehicle (in degrees)"
        }
      }
    },
    "cameraMedia": {
      "$ref": "#/$defs/CameraMediaReference"
    },
    "metadata": {
      "$ref": "#/$defs/DeletableEntityMetadata"
    },
    "raw": {
      "$ref": "#/$defs/RawDataList"
    }
  },
  "required": [
    "id",
    "sourceId",
    "provider",
    "type",
    "vehicle",
    "startedAt",
    "metadata"
  ],
  "x-description": "A normalized record of a safety-related incident that occurred during a vehicle's operation. These events are detected and recorded by the telematics provider's system.",
  "$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."
    },
    "CameraMediaFileReference": {
      "title": "Camera Media Reference",
      "type": "object",
      "properties": {
        "available": {
          "type": "boolean",
          "description": "Indicates whether the camera media file is available for retrieval."
        },
        "sourceId": {
          "type": "string",
          "description": "The identifier for the camera media file in the source system."
        }
      },
      "required": [
        "available"
      ]
    },
    "CameraMediaReference": {
      "title": "Camera Media Reference",
      "type": "object",
      "properties": {
        "frontFacing": {
          "description": "The front facing camera media.",
          "$ref": "#/$defs/CameraMediaFileReference"
        },
        "rearFacing": {
          "description": "The rear facing camera media.",
          "$ref": "#/$defs/CameraMediaFileReference"
        }
      }
    },
    "Coordinates": {
      "title": "Coordinates",
      "type": "object",
      "properties": {
        "longitude": {
          "type": "number"
        },
        "latitude": {
          "type": "number"
        }
      },
      "required": [
        "longitude",
        "latitude"
      ]
    },
    "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)."
        }
      }
    },
    "DeletableEntityMetadata": {
      "title": "DeletableEntityMetadata",
      "type": "object",
      "description": "Internal metadata about the record.",
      "required": [
        "addedAt",
        "modifiedAt"
      ],
      "properties": {
        "addedAt": {
          "$ref": "#/$defs/AddedAt"
        },
        "modifiedAt": {
          "$ref": "#/$defs/ModifiedAt"
        },
        "deletedAt": {
          "$ref": "#/$defs/DeletedAt"
        }
      }
    },
    "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"
    },
    "DriverId": {
      "title": "DriverId",
      "description": "Unique identifier for the driver in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^drv_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "ExpandableDriver": {
      "oneOf": [
        {
          "$ref": "#/$defs/DriverId"
        },
        {
          "$ref": "#/$defs/ExpandedDriver"
        }
      ]
    },
    "ExpandableVehicle": {
      "oneOf": [
        {
          "$ref": "#/$defs/VehicleId"
        },
        {
          "$ref": "#/$defs/ExpandedVehicle"
        }
      ]
    },
    "ExpandedDriver": {
      "title": "Expanded Driver",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/DriverId"
        },
        "sourceId": {
          "$ref": "#/$defs/SourceId"
        },
        "provider": {
          "$ref": "#/$defs/ProviderCode"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ],
          "description": "The status in the providers system"
        },
        "firstName": {
          "type": "string"
        },
        "middleName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": {
          "title": "Phone",
          "type": "string",
          "pattern": "^\\+?\\d{10,14}$",
          "description": "Phone number formatted in [E.164](https://www.twilio.com/docs/glossary/what-e164) formatting"
        },
        "username": {
          "type": "string",
          "description": "The driver's username for login purposes"
        },
        "license": {
          "type": "object",
          "properties": {
            "state": {
              "$ref": "#/$defs/State"
            },
            "number": {
              "type": "string"
            }
          }
        },
        "groups": {
          "type": "array",
          "description": "The groups the driver belongs to.",
          "items": {
            "$ref": "#/$defs/GroupId"
          }
        },
        "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 driver in Terminal."
    },
    "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."
    },
    "GForce": {
      "title": "G-Force",
      "type": "number",
      "description": "Acceleration as a factor of gravity (g)"
    },
    "GroupId": {
      "title": "GroupId",
      "type": "string",
      "format": "ulid"
    },
    "HeadingInDegrees": {
      "title": "Heading In Degrees",
      "type": "number",
      "description": "Heading in degrees"
    },
    "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."
    },
    "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)."
    },
    "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"
      }
    },
    "SafetyEventId": {
      "title": "SafetyEventId",
      "type": "string",
      "format": "ulid",
      "pattern": "^sft_evt_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "SafetyEventType": {
      "title": "SafetyEventType",
      "type": "string",
      "enum": [
        "harsh_brake",
        "harsh_acceleration",
        "harsh_turn",
        "speeding",
        "crash",
        "near_crash",
        "tailgating",
        "cell_phone",
        "distracted",
        "drowsiness",
        "smoking",
        "seat_belt_violation",
        "stop_sign_violation",
        "red_light_violation",
        "unsafe_lane_change",
        "camera_obstruction",
        "eating_and_drinking",
        "rolling_stop",
        "unsafe_parking"
      ]
    },
    "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."
    },
    "SpeedInKPH": {
      "title": "Speed In KPH",
      "type": "number",
      "description": "Speed in KPH rounded to 2 decimal places."
    },
    "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"
    },
    "VehicleId": {
      "title": "VehicleId",
      "description": "Unique identifier for the vehicle in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^vcl_[0-9A-HJKMNP-TV-Z]{26}$"
    }
  }
}