{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Telemachus Core v0.2",
  "$id": "https://telemachus3.github.io/telemachus-spec/schemas/telemachus_core_v0.2.json",
  "description": "Telemachus Core v0.2 — Open pivot schema for high-frequency mobility and telematics data: GNSS, motion, IMU, powertrain, events, quality, context, and source metadata.",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "UTC ISO-8601 timestamp"
    },
    "vehicle_id": {
      "type": "string",
      "description": "Unique vehicle identifier (fleet-specific)"
    },
    "position": {
      "type": "object",
      "description": "Geographical position and derived attributes",
      "properties": {
        "lat": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude (decimal degrees, WGS84)" },
        "lon": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude (decimal degrees, WGS84)" },
        "altitude_m": { "type": "number", "description": "Altitude in meters (optional)" },
        "heading_deg": { "type": "number", "minimum": 0, "maximum": 360, "description": "Heading in degrees (0-360)" }
      },
      "required": ["lat", "lon"]
    },
    "motion": {
      "type": "object",
      "properties": {
        "speed_kph": { "type": "number", "minimum": 0, "description": "Speed in km/h" },
        "bearing_deg": { "type": "number", "minimum": 0, "maximum": 360, "description": "Bearing (optional)" }
      }
    },
    "quality": {
      "type": "object",
      "description": "GNSS quality metrics",
      "properties": {
        "hdop": { "type": "number", "description": "Horizontal dilution of precision" },
        "vdop": { "type": "number" },
        "pdop": { "type": "number" },
        "num_satellites": { "type": "integer", "minimum": 0 },
        "fix_type": { "type": "string", "enum": ["none", "2d", "3d", "dgps", "rtk"] }
      }
    },
    "imu": {
      "type": "object",
      "description": "Inertial Measurement Unit (IMU) raw or aggregated data (optional). Units SI: m/s² for accel, rad/s for gyro, µT for magnetometer",
      "properties": {
        "accel": {
          "type": "object",
          "properties": {
            "x_ms2": { "type": "number" },
            "y_ms2": { "type": "number" },
            "z_ms2": { "type": "number" }
          }
        },
        "gyro": {
          "type": "object",
          "properties": {
            "x_rads": { "type": "number" },
            "y_rads": { "type": "number" },
            "z_rads": { "type": "number" }
          }
        },
        "mag": {
          "type": "object",
          "properties": {
            "x_ut": { "type": "number" },
            "y_ut": { "type": "number" },
            "z_ut": { "type": "number" }
          }
        },
        "sample_rate_hz": { "type": "number", "description": "Sampling rate in Hz (if applicable)" }
      }
    },
    "powertrain": {
      "type": "object",
      "description": "Powertrain & electrical data (CAN/OBD). Field availability depends on provider/OBD access.",
      "properties": {
        "rpm": { "type": "number", "minimum": 0, "description": "Engine RPM" },
        "odometer_km": { "type": "number", "minimum": 0, "description": "Odometer in kilometers" },
        "throttle_pct": { "type": "number", "minimum": 0, "maximum": 100 },
        "coolant_temp_c": { "type": "number", "description": "Engine coolant temperature (°C)" },
        "battery_voltage_v": { "type": "number", "description": "12V battery voltage (V)" }
      }
    },
    "energy": {
      "type": "object",
      "description": "Energy & fuel metrics (extended FieldGroup per RFC-0004). Optional.",
      "properties": {
        "fuel_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Fuel level percentage (ICE/HEV)" },
        "fuel_l": { "type": "number", "minimum": 0, "description": "Fuel amount in liters" },
        "fuel_rate_lph": { "type": "number", "minimum": 0, "description": "Fuel consumption rate (L/h)" },
        "consumed_kwh": { "type": "number", "minimum": 0, "description": "Energy consumed (kWh) for EV/HEV" },
        "recovered_kwh": { "type": "number", "minimum": 0, "description": "Regenerated energy (kWh)" },
        "state_of_charge_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "EV battery state of charge (%)" },
        "charging_status": { "type": "string", "enum": ["disconnected", "charging", "charged", "error"], "description": "EV charging state" },
        "energy_source": { "type": "string", "enum": ["ice", "hev", "phev", "bev"], "description": "Primary energy source/type" }
      }
    },
    "events": {
      "type": "array",
      "description": "Event list detected or reported by device/server (harsh braking, overspeed, geofence, etc.)",
      "items": {
        "type": "object",
        "properties": {
          "event_id": { "type": "string", "description": "Optional unique event identifier" },
          "type": { "type": "string" },
          "severity": { "type": "string", "enum": ["low", "medium", "high"], "description": "Optional severity" },
          "start": { "type": "string", "format": "date-time" },
          "end": { "type": "string", "format": "date-time" },
          "metadata": { "type": "object", "additionalProperties": true }
        }
      }
    },
    "context": {
      "type": "object",
      "description": "Optional contextual enrichments (topography, weather, road attributes)",
      "properties": {
        "topography": {
          "type": "object",
          "properties": {
            "slope_deg": { "type": "number" },
            "surface_type": { "type": "string" }
          }
        },
        "weather": {
          "type": "object",
          "properties": {
            "temp_c": { "type": "number" },
            "precip_mm": { "type": "number" }
          }
        },
        "environmental_impact": {
          "type": "object",
          "properties": {
            "co2_g_km": { "type": "number", "minimum": 0, "description": "Estimated CO₂ emissions (g/km)" },
            "energy_recovery_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Regenerative braking share (%)" }
          }
        },
        "urban": {
          "type": "object",
          "properties": {
            "speed_limit_kph": { "type": "number", "minimum": 0 },
            "road_type": { "type": "string", "description": "e.g., motorway, primary, residential" }
          }
        },
        "safety": {
          "type": "object",
          "properties": {
            "risk_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relative risk score (0–1)" }
          }
        }
      },
      "additionalProperties": true
    },
    "source": {
      "type": "object",
      "description": "Provenance metadata (which provider, device id, ingestion time)",
      "properties": {
        "schema_version": { "type": "string", "enum": ["0.2"], "description": "Telemachus schema version" },
        "provider": { "type": "string" },
        "device_id": { "type": "string" },
        "ingest_timestamp": { "type": "string", "format": "date-time" }
      }
    }
  },
  "required": ["timestamp", "vehicle_id", "position"],
  "additionalProperties": false
}