@myrobotaxi/contracts 0.2.0 → 0.4.0

package/schemas/vehicle-summary.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://myrobotaxi.com/schemas/vehicle-summary.schema.json",
+  "title": "VehicleListResponse",
+  "description": "Envelope returned by GET /api/vehicles. Wraps an array of VehicleSummary rows under the `items` key. Pagination fields are reserved per rest-api.md §7.0 and intentionally absent in v1. The envelope itself is part of the wire contract: consumers MUST NOT strip it silently.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items"],
+  "properties": {
+    "items": {
+      "type": "array",
+      "description": "Per-vehicle summary rows for vehicles the caller has access to. Order is server-defined (currently ORDER BY Vehicle.createdAt ASC in the telemetry list query). An empty array means the caller has no vehicles (or is a v1 viewer-tier caller — see rest-api.md §7.0 RBAC v1 implementation note).",
+      "items": { "$ref": "#/$defs/VehicleSummary" }
+    }
+  },
+  "$defs": {
+    "VehicleSummary": {
+      "title": "VehicleSummary",
+      "description": "Lean per-vehicle row returned by GET /api/vehicles. A list-view projection of VehicleState containing only the fields the catalog UI needs (identity, model/year/color, status, charge headline, last-updated). No GPS, no navigation, no climate, no encrypted-at-rest fields. Mirrors the Go `vehicleSummary` struct in telemetry/internal/telemetry/vehicles_list_handler.go and the `VehicleSummary` shape in telemetry/specs/rest.openapi.yaml. Use VehicleState for the full snapshot/WebSocket payload; use VehicleSummary for list endpoints.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "vehicleId",
+        "name",
+        "model",
+        "year",
+        "color",
+        "vinLast4",
+        "status",
+        "chargeLevel",
+        "estimatedRange",
+        "lastUpdated",
+        "role"
+      ],
+      "properties": {
+        "vehicleId": {
+          "type": "string",
+          "description": "Opaque database identifier (cuid). NOT the VIN. All SDK API calls use this ID (FR-4.2). Matches VehicleState.vehicleId.",
+          "x-classification": "P0",
+          "examples": ["clxyz1234567890abcdef"]
+        },
+        "name": {
+          "type": "string",
+          "description": "User-assigned vehicle name from DB Vehicle.name. Matches VehicleState.name.",
+          "x-classification": "P0",
+          "examples": ["Optimus"]
+        },
+        "model": {
+          "type": "string",
+          "description": "Vehicle model (e.g., 'Model 3', 'Model Y'). Sourced from DB Vehicle.model. Matches VehicleState.model.",
+          "x-classification": "P0",
+          "examples": ["Model 3"]
+        },
+        "year": {
+          "type": "integer",
+          "description": "Model year. Sourced from DB Vehicle.year. Matches VehicleState.year.",
+          "x-classification": "P0",
+          "examples": [2024]
+        },
+        "color": {
+          "type": "string",
+          "description": "Vehicle exterior color. Sourced from DB Vehicle.color. Matches VehicleState.color.",
+          "x-classification": "P0",
+          "examples": ["Midnight Silver Metallic"]
+        },
+        "vinLast4": {
+          "type": "string",
+          "description": "Last 4 characters of the vehicle's 17-character VIN. The full VIN is never emitted on the list endpoint — vinLast4 is sufficient for human disambiguation in the catalog UI without exposing the full identifier. Empty string when the VIN is unknown.",
+          "x-classification": "P1",
+          "examples": ["3F5A"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["driving", "parked", "charging", "offline", "in_service"],
+          "description": "Derived vehicle status snapshot at the time of the last telemetry update. Same enum as VehicleState.status.",
+          "x-classification": "P0"
+        },
+        "chargeLevel": {
+          "type": "integer",
+          "description": "Battery state of charge snapshot at the time of the last telemetry update. Same semantics as VehicleState.chargeLevel.",
+          "x-classification": "P0",
+          "x-unit": "percent",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "estimatedRange": {
+          "type": "integer",
+          "description": "Estimated remaining driving range snapshot at the time of the last telemetry update. Same semantics as VehicleState.estimatedRange.",
+          "x-classification": "P0",
+          "x-unit": "miles",
+          "minimum": 0
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of the most recent telemetry update applied to this vehicle. Same semantics as VehicleState.lastUpdated. Telemetry emits RFC 3339 UTC strings (e.g., '2026-05-25T17:30:00Z').",
+          "x-classification": "P0"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["owner", "viewer"],
+          "description": "RBAC role the caller holds against this vehicle. v1 only emits 'owner' rows (every vehicle returned is one the caller owns via Vehicle.userId). The 'viewer' value is reserved for the viewer-merged invite-read pathway tracked as a follow-up — see rest-api.md §7.0 RBAC v1 implementation note.",
+          "x-classification": "P0"
+        }
+      }
+    }
+  }
+}