Amplitude Event Structure

{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/amplitude/refs/heads/main/json-structure/amplitude-event-structure.json",
  "name": "Amplitude Event",
  "description": "Schema for an Amplitude analytics event used in the HTTP V2 API and exported via the Export API. Represents a single user action or system occurrence tracked in Amplitude.",
  "type": "object",
  "required": [
    "event_type"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "description": "A readable user identifier. Required unless device_id is present.",
      "minLength": 5
    },
    "device_id": {
      "type": "string",
      "description": "A device-specific identifier. Required unless user_id is present."
    },
    "event_type": {
      "type": "string",
      "description": "The name of the event being tracked.",
      "minLength": 1
    },
    "time": {
      "type": "int32",
      "description": "The timestamp of the event in milliseconds since epoch."
    },
    "event_properties": {
      "type": "object",
      "description": "A dictionary of key-value pairs representing properties of the event.",
      "additionalProperties": true
    },
    "user_properties": {
      "type": "object",
      "description": "A dictionary of key-value pairs representing properties of the user. Supports set, setOnce, add, append, prepend, unset, and remove operations.",
      "additionalProperties": true
    },
    "groups": {
      "type": "object",
      "description": "A dictionary of group type to group name mappings.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "group_properties": {
      "type": "object",
      "description": "A dictionary of key-value pairs representing properties of the group.",
      "additionalProperties": true
    },
    "app_version": {
      "type": "string",
      "description": "The version of the application sending the event."
    },
    "platform": {
      "type": "string",
      "description": "The platform of the device, such as iOS, Android, or Web."
    },
    "os_name": {
      "type": "string",
      "description": "The name of the operating system."
    },
    "os_version": {
      "type": "string",
      "description": "The version of the operating system."
    },
    "device_brand": {
      "type": "string",
      "description": "The brand of the device."
    },
    "device_manufacturer": {
      "type": "string",
      "description": "The manufacturer of the device."
    },
    "device_model": {
      "type": "string",
      "description": "The model of the device."
    },
    "carrier": {
      "type": "string",
      "description": "The carrier of the device."
    },
    "country": {
      "type": "string",
      "description": "The country of the user.",
      "maxLength": 2
    },
    "region": {
      "type": "string",
      "description": "The region or state of the user."
    },
    "city": {
      "type": "string",
      "description": "The city of the user."
    },
    "dma": {
      "type": "string",
      "description": "The designated market area of the user."
    },
    "language": {
      "type": "string",
      "description": "The language setting of the user."
    },
    "price": {
      "type": "double",
      "description": "The price of the item purchased in a revenue event."
    },
    "quantity": {
      "type": "int32",
      "description": "The quantity of the item purchased.",
      "minimum": 0
    },
    "revenue": {
      "type": "double",
      "description": "The revenue generated by the event. Use negative values for refunds."
    },
    "productId": {
      "type": "string",
      "description": "The identifier for the product in a revenue event."
    },
    "revenueType": {
      "type": "string",
      "description": "The type of revenue, such as purchase or refund."
    },
    "location_lat": {
      "type": "double",
      "description": "The latitude of the user's location.",
      "minimum": -90,
      "maximum": 90
    },
    "location_lng": {
      "type": "double",
      "description": "The longitude of the user's location.",
      "minimum": -180,
      "maximum": 180
    },
    "ip": {
      "type": "string",
      "description": "The IP address of the user. Use $remote to use the upload request IP."
    },
    "idfa": {
      "type": "string",
      "description": "The Identifier for Advertiser (iOS)."
    },
    "idfv": {
      "type": "string",
      "description": "The Identifier for Vendor (iOS)."
    },
    "adid": {
      "type": "string",
      "description": "The Google Play Services advertising ID (Android)."
    },
    "android_id": {
      "type": "string",
      "description": "The Android ID."
    },
    "event_id": {
      "type": "int32",
      "description": "An incrementing counter to distinguish events with identical user_id and timestamps."
    },
    "session_id": {
      "type": "int32",
      "description": "The start time of the session in milliseconds since epoch. Use -1 for events outside a session."
    },
    "insert_id": {
      "type": "string",
      "description": "A unique identifier for deduplication. Amplitude deduplicates events with the same insert_id and device_id or user_id within 7 days.",
      "maxLength": 36
    }
  },
  "anyOf": [
    {
      "required": [
        "user_id"
      ]
    },
    {
      "required": [
        "device_id"
      ]
    }
  ]
}