# GoRoamIt JSON template — field guide v1

Last checked: October 17, 2026. Compatible parser check: GoRoamIt iOS 1.0 (54).

Download goroamit-blank-trip-v1.json and keep the outer format/version/trips/activeTripId wrapper. This is a plaintext planning template, NOT an encrypted private backup. It contains no itinerary, real people, reservations or private data. No website upload or account is needed to download it.

## Quick start

1. Save the JSON to Files. Edit with a JSON-capable text editor, or ask a planning assistant to fill it using this guide. Preserve valid JSON, not a Markdown code block in the saved .json file.
2. Fill the trip name, origin, destination cities and actual dates. Set both clocks explicitly; UTC is a neutral placeholder, NOT a detected home/destination timezone. The template's USD is also a placeholder budget currency, not a currency conversion.
3. Back up existing GoRoamIt data first. In the app: Settings > Local storage & recovery > Import backup > choose your .json > inspect the counts > Add recovery copies. This plaintext template needs no password. The app may append a localized Recovered suffix.
4. A recovery import adds a separate trip copy. It does not merge into an existing trip or update previous imports. Free includes one current editable trip; if prompted to replace an existing trip, cancel until you have chosen what to keep. Do not delete data just to try a template.

The untouched blank file can be parsed/imported. Its empty dates produce an incomplete-dates warning; that is expected, not a corrupt file. You may fill these details in the app. There are zero activities, tasks, travelers, places, notes or media until you add them. The template's fixed creation timestamp identifies the template revision, not the date you created or booked your trip.

## Trip fields

- `format`: keep `goroamit-private-recovery`; `version`: keep numeric `1`.
- `activeTripId`: must exactly equal the `id` of a trip in `trips`.
- `id`: nonempty stable string. Recovery creates a new root trip ID; integer child record IDs must be unique inside each collection.
- `name`, `origin`: strings. `destinations`: array of city-name strings, not a comma-separated string.
- `startDate`, `endDate`: real `YYYY-MM-DD` local dates, or `""` while incomplete. Start must not follow end. International flight dates can extend a ground itinerary; do not silently ignore the homebound leg.
- `status`: `active`, `archived` or `deleted`; use `active` for a new template. Keep `isDemo: false` for a normal editable trip.
- `coverPhoto`: `""` if none. Use only images you may lawfully use. Do not paste unresolved `blob:` or `goroamit-media:` references from another device. Remote image URLs can disclose network information when loaded.
- `createdAt`, `updatedAt`: ISO timestamps for your own record; they are not reservation dates.
- `clocks`: all four fields required. Use real IANA zones such as `America/New_York` and `Europe/Madrid`, not `GMT+2`, a device guess or a fixed UTC offset. Set labels to human-readable city/region names.
- `budget`: finite numeric `total`, three-letter `currency`, `basis` (`group` or `person`), booleans `includeTransport`, `includeStay`, `countEstimates`, and an `exchangeRates` object. Base-currency rate is 1; do not invent rates for other currencies.

For a group, specify whether each amount covers all travelers, one person, one room or all rooms. A five-person/three-room stay must not be costed as 2.5 rooms. Count a multi-night stay total once, not again at checkout or on every night. A budget is not proof of payment.

## Collection field shapes

Insert objects into the matching array. The following are field examples, not a real itinerary or confirmed booking. Dates/times and names must be replaced when used. Required empty strings remain strings, not null. Do not add comments or trailing commas to JSON.

### Member example (`members`)

```json
{
  "id": 1, "name": "Traveler 1", "initials": "T1", "phone": "",
  "start": "", "diet": "", "bags": 1, "note": "", "color": "#245947"
}
```

`start` is the traveler's departure/joining location. Confirm dietary requirements with the actual person; do not invent allergies, diagnoses, identity details or phone numbers. Use `note` for agreed rooming/coordination. Keep sensitive details out of publicly shared plaintext files.

### Activity example (`activities`)

```json
{
  "id": 1, "date": "2026-11-07", "time": "10:00", "endTime": "11:00",
  "timeZoneId": "Europe/Madrid", "endTimeZoneId": "Europe/Madrid",
  "title": "Replace with your activity", "type": "Culture",
  "place": "", "contact": "", "price": 0, "currency": "EUR",
  "exchangeRate": 1, "booked": false, "status": "Planned", "split": "all",
  "notes": "", "extras": [], "bookingUrl": ""
}
```

Suggested activity types: `Food`, `Culture`, `Tour`, `Transport`, `Stay`, `Shopping`, `Wellness`, `Other`. Times are 24-hour `HH:mm`; use the destination's actual local timezone. Add `endDate` for overnight events. End must follow start. Only use `Booked`/`Confirmed` and `booked: true` if that status is factual. Notes can include source URLs, checked dates, estimate assumptions and opening/availability limits. `extras` can contain `{ "label": "Room request", "value": "..." }`. Optional integer `placeId` must match a saved Place in the same trip. Omit it when there is no linked Place. Do not fabricate order numbers, live fares or confirmed availability.

### Structured stay (additional activity fields)

For a `Stay`, the top-level `date`, `time`, `endDate`, `endTime` must match `stayDetails`. Keep one group-total price for that stay and put room count/occupants in `notes` and `extras`; no automatic room allocation or settlement is implied.

```json
{
  "endDate": "2026-11-11",
  "stayDetails": {
    "propertyName": "Your hotel", "confirmationNumber": "",
    "checkIn": { "date": "2026-11-07", "time": "15:00", "place": "Your hotel", "timeZoneId": "Europe/Madrid" },
    "checkOut": { "date": "2026-11-11", "time": "09:00", "place": "Your hotel", "timeZoneId": "Europe/Madrid" }
  }
}
```

These times are examples, not a hotel's policy. A genuine stay reserves accommodation, not the traveler's entire daytime schedule.

### Structured transport (additional activity fields)

For `Transport`, keep the activity's outer dates/times/zones consistent with the departure/arrival. Each point uses its own location's timezone. Do not manually invent `instantEpochMs`; omit derived fields and let GoRoamIt normalize when edited.

```json
{
  "transportLegs": [{
    "id": "leg-1", "mode": "Train", "carrier": "", "referenceNumber": "",
    "departure": { "date": "2026-11-07", "time": "10:00", "place": "Departure station", "timeZoneId": "Europe/Madrid" },
    "arrival": { "date": "2026-11-07", "time": "12:00", "place": "Arrival station", "timeZoneId": "Europe/Madrid" }
  }]
}
```

Modes: `Flight`, `Train`, `Bus`, `Car`, `Ferry`, `Cruise`, `Other`. Do not call an illustrative planning window a verified timetable.

### Task example (`tasks`)

```json
{ "id": 1, "title": "Confirm arrangements", "category": "Planning", "assignee": null, "done": false, "dueDate": "2026-11-01", "url": "" }
```

`assignee` is null or a member's integer ID. Omit `dueDate`/`url` if not needed. A task is not marked done simply because it appears in this file.

### Place example (`places`)

```json
{
  "id": 1, "name": "Your place", "type": "Culture", "address": "",
  "mapUrl": "", "website": "", "bookingUrl": "", "contact": "",
  "notes": "", "photo": ""
}
```

Use full http/https links; keep source, last check and uncertainty in `notes`. A map name-search link is not a verified coordinate; do not mark an unresolved place as confirmed. No photo is required. Consider opening days, group capacity and entry points before scheduling.

### Note example (`notes`)

```json
{ "id": 1, "title": "Trip overview", "body": "", "date": "2026-11-01", "pinned": true, "photos": [], "audio": [] }
```

Useful notes: route overview, rooming list, traveler-confirmed dietary needs, group cost assumptions, transfer buffers, rainy-day alternatives, source list and booking checklist. Do not claim safety, accessibility or current prices without evidence.

## Optional instruction for a planning assistant

“Fill the attached GoRoamIt blank JSON using this field guide. Ask for actual origin, destinations, dates, travelers, rooms, budget, currency and language. Research suitable official and travel-blog sources where needed, record URLs/check dates and distinguish estimates from confirmed bookings. Set home and destination IANA timezones explicitly. Keep a single trip, preserve the recovery wrapper and all required collections/fields, use unique integer child IDs and valid links/references, mark unbooked activities Planned, leave unknown private details blank, and return one valid JSON file without Markdown fences. Never invent reservations, medical information or live fares. Show unresolved decisions before import.”

## Scope

This documents the current GoRoamIt recovery-compatible template, not a generic JSON travel standard or a promise that every third-party itinerary JSON imports. CSV templates and encrypted backups are different formats. Parsing validation does not prove that filled content is accurate, booked or safe; review the import preview and actual trip after saving. No App Store approval or availability claim is made by this download.