Merge pull request #22 from Ashi-Ashish/6-define-telematics_event-schema-json

Author: Ashi-Ashish

.github/workflows/schema-validate.yml

@@ -0,0 +1,15 @@
+name: Schema Validate
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+jobs:
+  ajv:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+      - run: npm ci || npm i
+      - run: npm run schema:check

README.md

@@ -17,4 +17,60 @@ docker compose up -d
 
 Notes:
 - docker-compose.yml now reads credentials from environment variables. Docker Compose automatically loads variables from a .env file in the project root.
-- It's not recommended to commit real secrets (like POSTGRES_PASSWORD) to GitHub. Use .env locally and secret managers or CI/CD secrets in production.
+- It's not recommended to commit real secrets (like POSTGRES_PASSWORD) to GitHub. Use .env locally and secret managers or CI/CD secrets in production.
+
+## Telematics Event Schema
+
+A canonical JSON Schema defines the message contract for events published to the `telematics.events` topic.
+
+- Location: `contracts/telematics_event.schema.json`
+- Version: 1.0.0 (backward-compatible changes in 1.x may only add optional fields or broaden enums)
+- Idempotency/ordering keys: `event_id`, `vehicle_id`, `ts` (epoch millis)
+- Strictness: unknown top-level properties are rejected (additionalProperties: false)
+
+Why we use it
+- Producers (e.g., simulator) can auto-generate valid payloads and fail fast on invalid data.
+- Consumers (e.g., StreamWorker) can validate and dead-letter bad messages, and upsert by `event_id` safely.
+- Enables contract/property tests in CI using a single source of truth.
+
+### Validate payloads with Docker (no local deps)
+
+You can validate JSON files against the schema using `ajv-cli` via a throwaway Node container:
+
+```bash
+# Validate example payloads
+docker run --rm -v "$PWD":/data node:20 npx -y ajv-cli \
+  validate -s /data/contracts/telematics_event.schema.json \
+  -d /data/examples/*.json
+
+# Validate a single file
+docker run --rm -v "$PWD":/data node:20 npx -y ajv-cli \
+  validate -s /data/contracts/telematics_event.schema.json \
+  -d /data/path/to/your_payload.json
+```
+
+Example files are provided:
+- `examples/valid_telematics_event.json`
+- `examples/invalid_telematics_event__missing_required.json`
+
+### Producer guidance
+- Always set `schema_version` to the schema version you targeted (e.g., `1.0.0`).
+- Generate stable UUIDs for `event_id` and a stable vehicle identifier for `vehicle_id`.
+- Use UTC epoch milliseconds in `ts`.
+- Provide `position.lat` and `position.lon`; other fields are optional but recommended when available.
+
+### Evolving the schema
+- Backward-compatible changes in 1.x: add optional properties, extend enums, loosen minima/maxima where safe.
+- Breaking changes: bump major and publish under a new `$id` path (e.g., `.../2-0-0`) and update `schema_version` expectations.
+
+
+## Unit consistency
+
+- We standardize on meters-per-second for speed inside the pipeline. The canonical field is `speed_mps` (m/s). If your API/UI needs kilometers-per-hour, convert at the edges (kph = mps * 3.6).
+- If you previously used `speed_kph` in docs or prototypes, consider it deprecated in favor of `speed_mps`.
+
+## Forward compatibility stance
+
+- The schema is intentionally strict at the root: `additionalProperties: false`. Unknown top-level fields are rejected to prevent silent contract drift and to keep consumers predictable.
+- If you later need looser forward-compatibility (accept unknown fields while validating the known required set), you can switch to JSON Schema 2020-12's `unevaluatedProperties: true` at the root. Keep `required` minimal to avoid false negatives.
+- Nullability guidance: prefer omitting fields when a value is unknown rather than sending `null`. If you must send nulls from some sources, we can broaden specific fields to allow unions like `["boolean","null"]` or `["number","null"]` in a backward-compatible minor version.

contracts/fixtures/invalid/invalid_event_missing_ts.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": "1.0.0",
+  "event_id": "b8d2a6cc-6b8f-4f86-8f7e-6a0f7a2e3b8f",
+  "vehicle_id": "veh-001",
+  "lat": 43.4516,
+  "lon": -80.4925
+}

contracts/fixtures/valid/valid_event.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": "1.0.0",
+  "event_id": "b8d2a6cc-6b8f-4f86-8f7e-6a0f7a2e3b8f",
+  "vehicle_id": "veh-001",
+  "driver_id": "drv-001",
+  "ts": "2025-09-15T12:34:56Z",
+  "lat": 43.4516,
+  "lon": -80.4925,
+  "speed_kph": 62.4,
+  "heading_deg": 180.0,
+  "accel_ms2": -0.5,
+  "fuel_pct": 78.0,
+  "odometer_km": 12435.7,
+  "meta": { "route_id": "rt-kwc-01", "source": "simulator" }
+}

contracts/telematics_event.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/telematics_event.schema.json",
+  "title": "Telematics Event",
+  "type": "object",
+  "required": ["event_id", "vehicle_id", "ts", "lat", "lon"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "event_id": { "type": "string", "format": "uuid" },
+    "vehicle_id": { "type": "string", "minLength": 1 },
+    "driver_id": { "type": "string", "minLength": 1 },
+    "ts": { "type": "string", "format": "date-time" },
+    "lat": { "type": "number", "minimum": -90, "maximum": 90 },
+    "lon": { "type": "number", "minimum": -180, "maximum": 180 },
+    "speed_kph": { "type": "number", "minimum": 0, "maximum": 300 },
+    "heading_deg": { "type": "number", "minimum": 0, "maximum": 360 },
+    "accel_ms2": { "type": "number", "minimum": -20, "maximum": 20 },
+    "fuel_pct": { "type": "number", "minimum": 0, "maximum": 100 },
+    "odometer_km": { "type": "number", "minimum": 0 },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "route_id": { "type": "string" },
+        "source": { "type": "string", "enum": ["simulator","device","replay"] }
+      }
+    }
+  }
+}