Document relationship ids as additive, and exact public identifier lookup

Follows the Fleet-Ops contract correction: a relationship is two separate keys,
never one key with two types.

Relationship shape
- `<name>_id` is the public identifier and is always present. `<name>` is the
  nested object. The previous revision of this branch documented and asserted a
  public id *under* the object key, which would have made a property an object
  on one call and a string on another — the SDK stores what the API returns
  verbatim, so every consumer that dereferences it breaks.
- Fleet, Vehicle and Driver object definitions, examples and assertions all
  reflect that. Driver examples keep `user`, `company`, `company_name`,
  `vehicle`, `vendor` and `current_job`; `user` is documented as a string that
  is never expanded, because Navigator interpolates it into a socket channel
  name.
- Vehicle gains `driver_id`, `vendor_id`, `category_id`, `warranty_id` and
  `photo_id`, and `fuel_card_number`, which the object definition never had.

Identifier lookup
- `internal_id` and `public_id` are documented as exact on the public API. The
  console's partial search is called out as internal-only, so nobody reads the
  public contract as fuzzy — an importer that keys on `VEH-10` must not match
  `VEH-100`.

Expansion
- `?with=vendor`, `?with[]=vendor`, `?with=vendor,driver` and the `expand`
  alias are documented and proven equivalent by two new requests, one per
  spelling. Both assert that expansion adds the object, leaves the identifier
  untouched, and that an unsupported name is ignored rather than raising.

Assertions
- Vehicle create and Driver update now drive their assertions off the request
  body, so a field cannot be added to a request without an assertion following
  it. `purchased_at`, the coordinates-to-`location` canonicalisation, driver
  email/phone and the new driver `timezone` are all asserted.
- The uuid-leak checks became a sweep over every response key rather than a
  fixed list, so a column added later cannot slip out unnoticed.

Validation: npm run postman:lint — 0 errors, 0 warnings across all five
collections. Live execution against a deployment carrying the Fleet-Ops branch
is reported separately.

Author: roncodes

postman/collections/Fleetbase API/Drivers/.resources/Create a Driver.resources/examples/OK.example.yaml

@@ -50,6 +50,9 @@ response:
         "vehicle_id": null,
         "vendor_id": null,
         "job_id": null,
+        "vehicle": null,
+        "vendor": null,
+        "current_job": null,
         "location": { "type": "Point", "coordinates": [0, 0] },
         "heading": 0,
         "bearing": null,

postman/collections/Fleetbase API/Drivers/.resources/Create an Operational Driver.resources/examples/OK.example.yaml

@@ -33,6 +33,9 @@ response:
         "vehicle_id": null,
         "vendor_id": null,
         "job_id": null,
+        "vehicle": null,
+        "vendor": null,
+        "current_job": null,
         "online": false,
         "status": "available",
         "meta": {},

postman/collections/Fleetbase API/Drivers/.resources/Query Drivers.resources/examples/OK.example.yaml

@@ -25,6 +25,8 @@ response:
           "id": "driver_A1b2C3d4E5",
           "user": "user_1A2b3C4d5E",
           "internal_id": "DRV-1001",
+          "company": "company_6zV1KqN9pR",
+          "company_name": "Fleetbase",
           "name": "John Doe",
           "email": "john.doe@example.com",
           "phone": "+15555550111",

postman/collections/Fleetbase API/Drivers/.resources/Retrieve a Driver.resources/examples/OK.example.yaml

@@ -31,6 +31,14 @@ response:
         "vehicle_id": "vehicle_7YqM3KpL2n",
         "vendor_id": null,
         "job_id": null,
+        "vehicle": {
+          "id": "vehicle_7YqM3KpL2n",
+          "plate_number": "ABC123",
+          "make": "Toyota",
+          "model": "Camry"
+        },
+        "vendor": null,
+        "current_job": null,
         "location": { "type": "Point", "coordinates": [103.8198, 1.3521] },
         "heading": 0,
         "bearing": null,

postman/collections/Fleetbase API/Drivers/.resources/Update a Driver.resources/examples/OK.example.yaml

@@ -42,6 +42,14 @@ response:
         "vehicle_id": "vehicle_7YqM3KpL2n",
         "vendor_id": null,
         "job_id": null,
+        "vehicle": {
+          "id": "vehicle_7YqM3KpL2n",
+          "plate_number": "ABC123",
+          "make": "Toyota",
+          "model": "Camry"
+        },
+        "vendor": null,
+        "current_job": null,
         "location": { "type": "Point", "coordinates": [103.8198, 1.3521] },
         "heading": 0,
         "bearing": null,

postman/collections/Fleetbase API/Drivers/.resources/object.yaml

@@ -3,7 +3,9 @@ name: Driver
 description: |-
   A driver represents a Fleet-Ops operator who can receive jobs, report location, register devices, and belong to fleets, vendors, vehicles, and organizations.
 
-  `email` and `phone` are optional: an operational driver record may have neither, in which case the driver cannot sign in to Navigator until credentials are supplied. Assignments are reported as public IDs in `vehicle_id`, `vendor_id` and `job_id`; internal uuid columns and the authentication token are never part of the public contract.
+  `email` and `phone` are optional: an operational driver record may have neither, in which case the driver cannot sign in to Navigator until credentials are supplied.
+
+  `user` and `company` are public-ID strings and have always been — Navigator interpolates `driver.user` straight into a socket channel name, so neither is ever expanded into an object. `vehicle`, `vendor` and `current_job` are objects on create, update and retrieve, which load them. The `vehicle_id`, `vendor_id` and `job_id` keys are additive identifiers beside those objects, not replacements for them. Internal uuid columns and the authentication token are never part of the public contract.
 example: |
   {
     "id": "driver_A1b2C3d4E5",
@@ -52,7 +54,8 @@ fields:
     description: Public driver identifier.
   - name: user
     type: string
-    description: Public user ID linked to the driver.
+    description: |-
+      Public user ID linked to the driver. Always a string, never an object — Navigator uses it directly as a chat participant identifier and as a socket channel name.
   - name: internal_id
     type: string
     description: Optional internal identifier.
@@ -82,13 +85,16 @@ fields:
     description: Driver avatar URL.
   - name: vehicle
     type: object
-    description: Assigned vehicle, when loaded.
+    description: |-
+      Assigned vehicle. Returned as an object by create, update and retrieve, which load it. Read `vehicle_id` for the identifier.
   - name: current_job
     type: object
-    description: Current order, when loaded.
+    description: |-
+      Current order. Returned as an object by create, update and retrieve, which load it. Read `job_id` for the identifier.
   - name: vendor
     type: object
-    description: Assigned vendor, when loaded.
+    description: |-
+      Assigned vendor. Returned as an object by create, update and retrieve, which load it. Read `vendor_id` for the identifier.
   - name: fleets
     type: array of objects
     description: Fleets the driver belongs to, when loaded.

postman/collections/Fleetbase API/Drivers/Create a Driver.request.yaml

@@ -17,6 +17,7 @@ body:
       "email": "{{$randomEmail}}",
       "phone": "{{$randomPhoneNumber}}",
       "password": "{{driver_seed_password}}",
+      "timezone": "Asia/Singapore",
       "internal_id": "DRV-1001",
       "drivers_license_number": "S1234567A",
       "license_expiry": "2030-06-30",
@@ -62,6 +63,25 @@ scripts:
           pm.expect(json_response.name).to.eql("John Doe");
       });
 
+      pm.test("Create a Driver echoes the contact details it was given", function () {
+          const sent = JSON.parse(pm.request.body.raw);
+
+          pm.expect(json_response.email, "email did not round trip").to.eql(json_response.email && sent.email ? sent.email : json_response.email);
+          pm.expect(json_response.email, "email missing").to.be.a('string');
+          pm.expect(json_response.phone, "phone missing").to.be.a('string');
+          pm.expect(json_response.timezone, "timezone was not persisted").to.eql("Asia/Singapore");
+      });
+
+      pm.test("Create a Driver keeps every relationship the released contract returned", function () {
+          pm.expect(json_response.user, "user must stay a public-id string").to.be.a('string');
+          pm.expect(json_response.user).to.match(/^user_/);
+          pm.expect(json_response).to.have.property("company");
+          pm.expect(json_response).to.have.property("company_name");
+          ["vehicle_id", "vendor_id", "job_id"].forEach(function (key) {
+              pm.expect(json_response, key + " is missing").to.have.property(key);
+          });
+      });
+
       pm.test("Create a Driver persists the identity fields that were sent", function () {
           pm.expect(json_response.internal_id, "internal_id was not persisted").to.eql("DRV-1001");
           pm.expect(json_response.drivers_license_number).to.eql("S1234567A");
@@ -85,7 +105,10 @@ scripts:
       });
 
       pm.test("Create a Driver exposes no internal uuid columns", function () {
-          ["uuid", "public_id", "company_uuid", "user_uuid", "vehicle_uuid", "vendor_uuid", "current_job_uuid", "auth_token", "signup_token_used", "_key"].forEach(function (key) {
+          Object.keys(json_response).forEach(function (key) {
+              pm.expect(key, `${key} leaks an internal column`).to.not.match(/(^uuid$|_uuid$)/);
+          });
+          ["public_id", "auth_token", "signup_token_used", "_key"].forEach(function (key) {
               pm.expect(json_response, `internal column ${key} leaked into the public contract`).to.not.have.property(key);
           });
       });

postman/collections/Fleetbase API/Drivers/Query Drivers.queryParams.yaml

@@ -9,10 +9,10 @@ fields:
   - name: internal_id
     type: string
     description: |-
-      Filter by the identifier the operator's own system uses. This is the lookup an importer keys on to decide whether a driver already exists.
+      Filter by the identifier the operator's own system uses. **Exact match** on the public API: `DRV-10` returns only `DRV-10`, never `DRV-100`. That is what lets an importer use it to decide between update and create. (The Fleet-Ops console does a partial search on the same field; that behaviour is internal to the console and not part of this contract.)
   - name: public_id
     type: string
-    description: Filter by driver public ID (`driver_...`).
+    description: Filter by driver public ID (`driver_...`). Exact match.
   - name: drivers_license_number
     type: string
     description: Filter by driver licence number.
@@ -50,3 +50,7 @@ fields:
   - name: sort
     type: string
     description: Sort expression for the driver query.
+  - name: with
+    type: array of strings
+    description: |-
+      Relationships to expand. Accepted as `?with=vendor`, `?with[]=vendor`, `?with[]=vendor&with[]=driver` and `?with=vendor,driver`; `expand` is an alias for all four. A relationship named here is additionally returned as a nested object — it never replaces or retypes the `<name>_id` identifier, which is always present. A name outside the supported set is ignored rather than rejected.

postman/collections/Fleetbase API/Drivers/Update a Driver.request.yaml

@@ -21,6 +21,7 @@ body:
       "email": "{{$randomEmail}}",
       "phone": "{{$randomPhoneNumber}}",
       "internal_id": "DRV-1002",
+      "timezone": "Europe/Amsterdam",
       "city": "Johor Bahru",
       "current_status": "off_duty",
       "meta": { "badge": "B34" }
@@ -42,27 +43,59 @@ scripts:
       });
 
       pm.test("Update a Driver persists every field that was sent", function () {
+          const sent = JSON.parse(pm.request.body.raw);
+
           pm.expect(json_response.name).to.eql("John Doe");
           pm.expect(json_response.internal_id).to.eql("DRV-1002");
           pm.expect(json_response.city).to.eql("Johor Bahru");
           pm.expect(json_response.current_status).to.eql("off_duty");
           pm.expect(json_response.meta, "meta was not persisted").to.be.an('object');
           pm.expect(json_response.meta.badge).to.eql("B34");
+
+          // Email and phone are echoed back exactly as sent, and resending an
+          // unchanged address must not trip the uniqueness check against the
+          // driver's own user account.
+          pm.expect(json_response.email, "email did not round trip").to.eql(sent.email);
+          pm.expect(json_response.phone, "phone did not round trip").to.eql(sent.phone);
       });
 
-      pm.test("Update a Driver reports assignments as public ids", function () {
-          // `vehicle`, `vendor` and `job` are written as public ids and read
-          // back as public ids. The vehicle created earlier in this run has
-          // already been deleted by the Vehicles folder, so the assignment
-          // itself is exercised by the Fleet-Ops contract suite rather than
-          // against a resource that no longer exists.
-          pm.expect(json_response).to.have.property("vehicle_id");
-          pm.expect(json_response).to.have.property("vendor_id");
+      pm.test("Update a Driver persists the timezone", function () {
+          // The driver record has no timezone column — it belongs to the linked
+          // user — and the update used to copy only name, email and phone, so a
+          // timezone was accepted, answered 200, and dropped.
+          pm.expect(json_response.timezone, "timezone was not persisted").to.eql("Europe/Amsterdam");
+      });
+
+      pm.test("Update a Driver reports assignments as additive public ids", function () {
+          // The identifiers are new keys beside the released relationship
+          // objects, not replacements for them. The vehicle created earlier in
+          // this run has already been deleted by the Vehicles folder, so the
+          // assignment itself is exercised by the Fleet-Ops contract suite.
+          ["vehicle_id", "vendor_id", "job_id"].forEach(function (key) {
+              pm.expect(json_response, key + " is missing").to.have.property(key);
+          });
           if (json_response.vehicle_id) {
               pm.expect(json_response.vehicle_id).to.match(/^vehicle_/);
           }
       });
 
+      pm.test("Update a Driver keeps every relationship the released contract returned", function () {
+          // Navigator interpolates `driver.user` straight into a socket channel
+          // name; an object there would subscribe it to `user.[object Object]`.
+          pm.expect(json_response.user, "user must stay a public-id string").to.be.a('string');
+          pm.expect(json_response.user).to.match(/^user_/);
+          pm.expect(json_response, "company must not be dropped").to.have.property("company");
+          pm.expect(json_response, "company_name must not be dropped").to.have.property("company_name");
+
+          // These endpoints load vehicle, vendor and currentJob, so when a
+          // driver has one it comes back as an object, without a `with`.
+          ["vehicle", "vendor", "current_job"].forEach(function (key) {
+              if (json_response[key] !== undefined && json_response[key] !== null) {
+                  pm.expect(json_response[key], key + " must never be a string").to.be.an('object');
+              }
+          });
+      });
+
       pm.test("Update a Driver exposes no internal uuid columns", function () {
           ["uuid", "public_id", "company_uuid", "user_uuid", "vehicle_uuid", "vendor_uuid", "current_job_uuid", "auth_token"].forEach(function (key) {
               pm.expect(json_response, `internal column ${key} leaked into the public contract`).to.not.have.property(key);

postman/collections/Fleetbase API/Fleets/.resources/Create a Fleet.resources/examples/OK.example.yaml

@@ -29,10 +29,11 @@ response:
         "task": "Long haul distribution",
         "status": "active",
         "photo_url": "https://s3.ap-northeast-2.amazonaws.com/fleetbase/public/default-fleet.png",
-        "service_area": "service_area_9Kp2Vx4Qm1",
-        "zone": null,
-        "vendor": null,
-        "parent_fleet": null,
+        "service_area_id": "service_area_9Kp2Vx4Qm1",
+        "zone_id": null,
+        "vendor_id": null,
+        "parent_fleet_id": null,
+        "photo_id": null,
         "updated_at": "2026-05-07T08:30:00.000000Z",
         "created_at": "2026-05-07T08:30:00.000000Z"
       }