{"slug": "designing-a-cross-border-airport-transfer-checklist-as-structured-data", "title": "Designing a Cross-Border Airport Transfer Checklist as Structured Data", "summary": "A developer outlined a structured-data approach for cross-border airport transfers, modeling Hong Kong Airport to Shenzhen and Dongguan bookings as a validated JSON and TypeScript schema rather than free-form chat requests. The design captures arrival, destination, passenger, luggage, and stop fields, enforces rules such as a six-passenger Alphard limit, and separates published reference fares (starting at RMB 800 to Shenzhen) from confirmed bookings. The writeup stresses that border procedures should carry a visible uncertainty note rather than being treated as a deterministic API response.", "body_md": "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.\n\nThis 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.\n\nA minimum request should capture:\n\nA small JSON object is easier to validate than a paragraph copied from a chat message:\n\n```\n{\n  \"arrival\": { \"date\": \"2026-10-18\", \"flight\": \"CX000\", \"airport\": \"HKG\" },\n  \"destination\": { \"city\": \"Shenzhen\", \"district\": \"Nanshan\", \"address\": \"Hotel name and entrance\" },\n  \"passengers\": 4,\n  \"children\": 1,\n  \"luggage\": [{ \"count\": 4, \"size\": \"24in\" }],\n  \"stops\": [],\n  \"needs\": [\"child-seat\"]\n}\n```\n\nFor 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.\n\nValidation should happen before dispatch. A lightweight TypeScript example:\n\n```\ntype TransferRequest = {\n  arrival: { date: string; flight: string; airport: \"HKG\" };\n  destination: { city: \"Shenzhen\" | \"Dongguan\"; district?: string; township?: string; address: string };\n  passengers: number;\n  children: number;\n  luggage: { count: number; size?: string }[];\n  stops: string[];\n};\n\nfunction validate(r: TransferRequest) {\n  if (!r.arrival.flight || !r.destination.address) throw new Error(\"Flight and exact address are required\");\n  if (r.destination.city === \"Shenzhen\" && !r.destination.district) throw new Error(\"Add the Shenzhen district\");\n  if (r.destination.city === \"Dongguan\" && !r.destination.township) throw new Error(\"Add the Dongguan township\");\n  if (r.passengers < 1 || r.passengers > 6) throw new Error(\"Check vehicle passenger capacity\");\n}\n```\n\nThe 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.\n\nA quote object should separate a published reference value from a confirmed booking:\n\n```\n{\n  \"currency\": \"RMB\",\n  \"referenceFare\": 800,\n  \"destinationScope\": \"listed Shenzhen districts\",\n  \"includes\": [\"driver\", \"fuel\", \"standard tolls\"],\n  \"requiresConfirmation\": [\"waiting\", \"night surcharge\", \"extra stops\", \"border procedure\"],\n  \"status\": \"reference\"\n}\n```\n\nThe 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.\n\nAvoid 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.\n\nThe last step is a message a traveler can review:\n\nPlease 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.\n\nThis exposes assumptions before payment and gives a dispatcher enough context to correct the data instead of guessing.\n\nA useful test matrix includes:\n\nThe 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.\n\nStructured 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.", "url": "https://wpnews.pro/news/designing-a-cross-border-airport-transfer-checklist-as-structured-data", "canonical_source": "https://dev.to/gavin_gui_262bf3b223662cd/designing-a-cross-border-airport-transfer-checklist-as-structured-data-34o8", "published_at": "2026-09-11 08:23:48+00:00", "updated_at": "2026-09-11 09:02:54.641979+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["CrossBorderHK", "Hong Kong Airport", "Shenzhen", "Dongguan", "TypeScript", "Alphard"], "alternates": {"html": "https://wpnews.pro/news/designing-a-cross-border-airport-transfer-checklist-as-structured-data", "markdown": "https://wpnews.pro/news/designing-a-cross-border-airport-transfer-checklist-as-structured-data.md", "text": "https://wpnews.pro/news/designing-a-cross-border-airport-transfer-checklist-as-structured-data.txt", "jsonld": "https://wpnews.pro/news/designing-a-cross-border-airport-transfer-checklist-as-structured-data.jsonld"}}