@myrobotaxi/contracts

Canonical wire-protocol schemas for the MyRoboTaxi platform.

• JSON Schema (draft-2020-12) under schemas/ — the language-neutral source of truth.
• Pre-generated TypeScript types under dist/ (via the ./types subpath) — produced by json-schema-to-typescript and committed to src/generated/ for diff review.

Consumed by @myrobotaxi/sdk, the Go telemetry server, and the react-frontend Next.js app.

Install

npm install @myrobotaxi/contracts

Usage

Type-only import (no runtime payload, tree-shakes to zero bytes):

import type { VehicleState, WebSocketEnvelope } from '@myrobotaxi/contracts/types';

Runtime schemas for Ajv / runtime validation:

import { schemas } from '@myrobotaxi/contracts';
// schemas.vehicleState, schemas.wsMessages, schemas.wsEnvelope

Raw JSON for non-JS consumers (Go, Swift):

./node_modules/@myrobotaxi/contracts/schemas/vehicle-state.schema.json
./node_modules/@myrobotaxi/contracts/schemas/ws-messages.schema.json
./node_modules/@myrobotaxi/contracts/schemas/ws-envelope.schema.json

What's in the generated TypeScript

Custom JSON Schema annotations from the source schemas — x-classification, x-atomic-group, x-unit, x-encrypted, x-tesla-proto-field — are folded into the generated TSDoc comments at codegen time. This means consumers can grep '@classification "P1"' inside their node_modules to find every sensitive field without leaving their editor.

/**
 * GPS latitude. Encrypted at rest (AES-256-GCM) per FR-11.1.
 *
 * @classification "P1"
 * @atomic-group "gps"
 * @encrypted true
 */
latitude: number;

Tool choice: json-schema-to-typescript

We picked json-schema-to-typescript v15+ over quicktype for three reasons:

1. Matches the telemetry repo's existing convention. The Go-side vehicle-state-schema.md §6.1 already documents json-schema-to-typescript as the TS-side tool. Picking the same one in the contracts package guarantees zero drift between the docs and the actual output.
2. Pure JS (no Rust binary). Easier to vendor into CI, no platform-specific install issues.
3. TSDoc-preserving. The description field on each JSON Schema property is copied verbatim into the generated TSDoc comment. quicktype produces leaner runtime helpers (parsers / serializers) but does not preserve descriptions as cleanly, and we don't need its runtime artifacts here.

The trade-off is that quicktype's discriminated-union handling for oneOf payloads is more idiomatic. The current schemas use a nullable-enum-with-explicit-null pattern instead of oneOf, so this doesn't bite us yet. If the schema set grows to need true discriminated unions, we may revisit.

Schema-authoring policy

Schemas in this repo are vendored from myrobotaxi/telemetry/docs/contracts/schemas/ — that repo is the current authoring home.

Until Phase 2 ships, schema changes require a paired PR to this repo (mirroring the change here, re-running codegen, bumping the version).

Phase 2 migration

A planned follow-up moves the schema authoring home from telemetry/docs/contracts/schemas/ into this repo, eliminating the paired-PR requirement. After Phase 2, the telemetry server's Go contract-tester will consume the published @myrobotaxi/contracts package directly.

Versioning policy

• Major version bump required for any wire-incompatible change (per NFR-3.37 in the telemetry docs).
• Minor version bump for additive, backwards-compatible additions (new optional fields, new message types, new enum members on append-only enums).
• Patch version bump for documentation / annotation changes that don't alter the generated TypeScript surface.

Development

npm install
npm run codegen        # regenerate src/generated/ from schemas/
npm run typecheck
npm run test
npm run build          # tsup → dist/

CI runs codegen and fails if src/generated/ drifts from the schemas — every schema bump must be paired with a regenerate-and-commit.

License

MIT