Data Upload Specification

This document describes the required JSON format for uploading historical Counter-UAS detection data to the Sentinel system. All uploaded files must conform to this schema for proper parsing and playback.

Supported Format

.json

JSON format only

Detection Record Schema

Each detection represents a single observation of a tracked object

Field	Type	Required	Description
id	string		Unique detection identifier
timestamp	string \| number		ISO 8601 string or Unix ms timestamp
lat	number		Latitude in decimal degrees (-90 to 90)
lng	number		Longitude in decimal degrees (-180 to 180)
altitude	number		Altitude in meters AGL
speed	number		Ground speed in m/s
heading	number		Track heading in degrees (0-360)
classification	enum		"drone" \| "bird" \| "aircraft" \| "unknown"
threatLevel	enum		"low" \| "medium" \| "high" \| "critical"
sensorId	string		ID of detecting sensor
confidence	number		Classification confidence (0.0 to 1.0)
signalStrength	number		RF signal strength in dBm
trackId	string		Track association identifier
frequency	number	Optional	RF frequency in MHz (if detected)

Event Record Schema

Events represent system actions, alerts, and state changes

Field	Type	Required	Description
id	string		Unique event identifier
timestamp	string \| number		ISO 8601 string or Unix ms timestamp
type	enum		"detection" \| "classification" \| "track_start" \| "track_end" \| "alert" \| "mitigation"
description	string		Human-readable event description
severity	enum		"info" \| "warning" \| "critical"
detectionId	string	Optional	Associated detection ID (for linking)

Sensor Configuration Schema

Define the sensor array used during data collection

Field	Type	Description
id	string	Unique sensor identifier
name	string	Display name for the sensor
type	enum	"radar" \| "rf" \| "optical" \| "acoustic"
lat	number	Sensor latitude
lng	number	Sensor longitude
range	number	Detection range in meters
status	enum	"online" \| "offline" \| "degraded"

Example JSON File

Complete example showing all required fields and structure

{
  "session": {
    "id": "session-2024-001",
    "name": "Perimeter Security Test",
    "startTime": "2024-01-01T08:00:00.000Z",
    "endTime": "2024-01-01T09:00:00.000Z",
    "source": "uploaded"
  },
  "sensors": [
    {
      "id": "sensor-001",
      "name": "Radar North",
      "type": "radar",
      "lat": 34.0522,
      "lng": -118.2437,
      "range": 5000,
      "status": "online"
    },
    {
      "id": "sensor-002",
      "name": "RF Scanner East",
      "type": "rf",
      "lat": 34.0525,
      "lng": -118.2400,
      "range": 3000,
      "status": "online"
    }
  ],
  "detections": [
    {
      "id": "det-001",
      "timestamp": "2024-01-01T08:05:00.000Z",
      "lat": 34.0550,
      "lng": -118.2450,
      "altitude": 120,
      "speed": 15.5,
      "heading": 45,
      "classification": "drone",
      "threatLevel": "medium",
      "sensorId": "sensor-001",
      "confidence": 0.92,
      "signalStrength": -65,
      "trackId": "track-001"
    },
    {
      "id": "det-002",
      "timestamp": "2024-01-01T08:05:30.000Z",
      "lat": 34.0555,
      "lng": -118.2445,
      "altitude": 125,
      "speed": 16.2,
      "heading": 48,
      "classification": "drone",
      "threatLevel": "high",
      "sensorId": "sensor-001",
      "confidence": 0.95,
      "signalStrength": -58,
      "frequency": 2437,
      "trackId": "track-001"
    }
  ],
  "events": [
    {
      "id": "evt-001",
      "timestamp": "2024-01-01T08:05:00.000Z",
      "type": "track_start",
      "description": "New track initiated: track-001",
      "severity": "info",
      "detectionId": "det-001"
    },
    {
      "id": "evt-002",
      "timestamp": "2024-01-01T08:05:00.500Z",
      "type": "detection",
      "description": "DRONE detected at 120m AGL",
      "severity": "info",
      "detectionId": "det-001"
    },
    {
      "id": "evt-003",
      "timestamp": "2024-01-01T08:05:30.100Z",
      "type": "alert",
      "description": "HIGH THREAT: track-001 approaching protected zone",
      "severity": "warning",
      "detectionId": "det-002"
    }
  ]
}

Validation Requirements

Timestamp format: Timestamps can be ISO 8601 strings (recommended) or Unix milliseconds. Both formats are supported.
Timestamp ordering: All detections and events must be sorted chronologically by timestamp
Track continuity: Detections sharing a trackId should represent the same physical object over time
Coordinate system: All coordinates must be in WGS84 (EPSG:4326) decimal degrees
Sensor references: All sensorId values in detections must match a sensor defined in the sensors array
File size: Maximum file size is 50MB. For larger datasets, split into multiple session files