# Designing a Cross-Border Airport Transfer Checklist as Structured Data

> Source: <https://dev.to/gavin_gui_262bf3b223662cd/designing-a-cross-border-airport-transfer-checklist-as-structured-data-34o8>
> Published: 2026-09-11 08:23:48+00:00

Travel logistics look simple until one missing field breaks the plan. A destination such as “Shenzhen” is not enough for a driver, dispatcher, or booking form. The useful design problem is to turn a human request into structured data that can be validated before a vehicle is assigned.

This post uses a Hong Kong Airport to Shenzhen or Dongguan transfer as a practical example. CrossBorderHK operates the referenced service; this is an engineering-oriented adaptation, not a neutral price comparison. I used AI assistance for outlining and copy editing, and the operator must verify current operational details before publishing or using the data.

A minimum request should capture:

A small JSON object is easier to validate than a paragraph copied from a chat message:

```
{
  "arrival": { "date": "2026-10-18", "flight": "CX000", "airport": "HKG" },
  "destination": { "city": "Shenzhen", "district": "Nanshan", "address": "Hotel name and entrance" },
  "passengers": 4,
  "children": 1,
  "luggage": [{ "count": 4, "size": "24in" }],
  "stops": [],
  "needs": ["child-seat"]
}
```

For Dongguan, replace district with township and include the industrial park or factory gate. This prevents a city-level quote from hiding the last-mile problem.

Validation should happen before dispatch. A lightweight TypeScript example:

```
type TransferRequest = {
  arrival: { date: string; flight: string; airport: "HKG" };
  destination: { city: "Shenzhen" | "Dongguan"; district?: string; township?: string; address: string };
  passengers: number;
  children: number;
  luggage: { count: number; size?: string }[];
  stops: string[];
};

function validate(r: TransferRequest) {
  if (!r.arrival.flight || !r.destination.address) throw new Error("Flight and exact address are required");
  if (r.destination.city === "Shenzhen" && !r.destination.district) throw new Error("Add the Shenzhen district");
  if (r.destination.city === "Dongguan" && !r.destination.township) throw new Error("Add the Dongguan township");
  if (r.passengers < 1 || r.passengers > 6) throw new Error("Check vehicle passenger capacity");
}
```

The six-passenger limit reflects the normal Alphard arrangement described by the operator: seven seats including the driver. Keep this rule in configuration so the UI and dispatch service share one source of truth.

A quote object should separate a published reference value from a confirmed booking:

```
{
  "currency": "RMB",
  "referenceFare": 800,
  "destinationScope": "listed Shenzhen districts",
  "includes": ["driver", "fuel", "standard tolls"],
  "requiresConfirmation": ["waiting", "night surcharge", "extra stops", "border procedure"],
  "status": "reference"
}
```

The published Hong Kong Airport to Shenzhen reference starts at RMB 800 / HKD 930. The listed Hong Kong to Dongguan route starts at RMB 1,200 / HKD 1,400 for some townships. Treat both as starting references. The final address, date, vehicle, waiting, and route conditions still need written confirmation.

Avoid representing border behavior as a deterministic API response. Passenger and luggage procedures can depend on permits, checkpoint, documents, lane, and on-site officer instructions. Store the planned procedure together with a visible uncertainty note.

The last step is a message a traveler can review:

Please quote a private transfer from HKG to [district/township and exact address]. Flight: [number/date]. Passengers: [count, children]. Luggage: [count and dimensions]. Stops: [list]. Please confirm total fare and currency, inclusions, waiting and overtime rules, cancellation terms, and planned border procedure.

This exposes assumptions before payment and gives a dispatcher enough context to correct the data instead of guessing.

A useful test matrix includes:

The test should verify that the interface asks for clarification, preserves the original request, and never silently converts a reference fare or estimated time into a guarantee.

Structured data does not remove uncertainty from cross-border travel. It makes the uncertainty visible early enough for a traveler, dispatcher, and driver to act on it.