Journey

A representation of a traveler's planned or actual movement associated with a transport instance — flight, vessel, train, bus, or land crossing.

The Journey object should contain the current normalized border-relevant travel state. It is not API-specific, PNR-specific, or Manifest-specific. Those are source records that update it, captured as JourneySourceSnapshot (see below).

This separation matters: a single journey may be updated multiple times — by an API push, then a PNR change, then a near-departure manifest. The Journey reflects the latest accepted state; the source snapshots are the auditable history.

Recommended relationship

Traveler
  1 ── *  Journey
            1 ── *  JourneySourceSnapshot
                      sourceSystem = API | PNR | MANIFEST | MANUAL

Attributes

Field	Type	Optionality	Format / Length	Source	Notes
journeyId	UUID / string	Mandatory	36 chars if UUID	TIS	Internal immutable Journey identifier
travelerId	UUID / string	Mandatory	36 chars if UUID	TIS	Reference to Traveler aggregate
transportType	enum	Mandatory	AIR, LAND, SEA	TIS / EES-aligned	Operational discriminator for the border context
operatorCode	string	Optional	2..3 uppercase alphanumeric	Latest accepted source snapshot	Carrier / operator code; for air, IATA 2-char preferred
conveyanceNumber	string	Optional	1..10 uppercase alphanumeric	Latest accepted source snapshot	Flight / vessel / train / bus reference
routeFrom	string / code	Optional	3..10 chars	Latest accepted source snapshot	Coded location preferred over free text; for air, airport code
routeTo	string / code	Optional	3..10 chars	Latest accepted source snapshot	As above
scheduledDeparture	datetime	Optional	ISO 8601	Latest accepted source snapshot	Border operations are time-sensitive
scheduledArrival	datetime	Optional	ISO 8601	Latest accepted source snapshot	As above
journeyStatus	enum	Mandatory	PLANNED, COMPLETED, INVALIDATED	TIS	Lifecycle of the normalized Journey
version	integer	Mandatory	latest accepted snapshot version	TIS	Increments with each accepted snapshot
currentSnapshotId	UUID / string	Mandatory	36 chars if UUID	TIS	Points to the latest accepted JourneySourceSnapshot
sourceSnapshots	array<reference>	Derived	n/a	TIS	Audit trail of source records that created or modified the Journey
primarySourceSystem	enum	Derived	API, PNR, MANIFEST, MANUAL	Derived	Convenience field; usually copied from the initial or latest accepted snapshot. Not the source of truth
primarySourceRecordRef	string	Derived	1..50	Derived	Convenience reference; the real source reference lives on the snapshot

---

JourneySourceSnapshot

The audit trail and source-of-truth lineage for the Journey. Each snapshot records what updated the Journey, from where, and when — keeping the Journey itself source-neutral.

This entity replaces older PNR-specific snapshot models. The same generic shape covers PNR, API (Advance Passenger Information), Manifest, and manual corrections.

Source semantics

Source	Meaning	Scope	Mapping to Journey
API	Advance Passenger Information / API-like traveler/document feed	Identity / document context with optional travel context	May create / update Journey if enough transport context exists
PNR	Passenger Name Record / booking record	Booking and itinerary context	Can create / update / invalidate Journey
MANIFEST	Carrier or transport manifest	Operational transport / passenger list	Strong operational source for Journey updates near departure / arrival
MANUAL	Manual correction or operational override	Administrative / operational correction	Can create / update / invalidate Journey

Attributes

Field	Type	Optionality	Format / Length	Source	Notes
snapshotId	UUID / string	Mandatory	36 chars if UUID	TIS	Internal immutable snapshot identifier
journeyId	UUID / string	Mandatory	36 chars if UUID	TIS	Reference to the Journey this snapshot modifies
sourceSystem	enum	Mandatory	API, PNR, MANIFEST, MANUAL	TIS / Integration	Key field that makes the snapshot source-neutral
sourceRecordRef	string	Mandatory	1..50	Source system	External source reference. PNR locator / API message ID / manifest reference / manual case ID
changeType	enum	Mandatory	INITIAL, UPDATE, CANCELLED, CORRECTION	TIS	Classifies how this snapshot affects the Journey
receivedTimeStamp	datetime	Mandatory	ISO 8601	TIS	When TIS received / accepted the source snapshot
effectiveAtTimeStamp	datetime	Optional	ISO 8601	Source / TIS	When the source says the change became effective
payloadHash	string	Recommended	SHA-256	TIS	Deduplication and integrity check
rawPayloadRef	string	Optional	URI / internal object ID	TIS	Pointer to raw payload if stored separately
operatorCode	string	Optional	2..3 uppercase alphanumeric	API / PNR / MANIFEST	Operator / carrier from this snapshot. May update Journey state
conveyanceNumber	string	Optional	1..10 uppercase alphanumeric	API / PNR / MANIFEST	Flight / movement number from this snapshot
routeFrom	string / code	Optional	3..10 chars	API / PNR / MANIFEST	Origin / location from this snapshot
routeTo	string / code	Optional	3..10 chars	API / PNR / MANIFEST	Destination / location from this snapshot
scheduledDeparture	datetime	Optional	ISO 8601	API / PNR / MANIFEST	Planned departure from this snapshot
scheduledArrival	datetime	Optional	ISO 8601	API / PNR / MANIFEST	Planned arrival from this snapshot
travelerIdentityRef	UUID / string	Optional	36 chars if UUID	API / MANIFEST	Reference to identity / document payload used for matching. Do not duplicate full identity fields here unless needed for audit
pnrLocator	string	Optional	usually 6 chars	PNR	PNR-specific convenience; can also be carried in sourceRecordRef when sourceSystem = PNR
bookingDate	date / datetime	Optional	ISO 8601	PNR	Useful for risk / audit; not Journey core
seatNumber	string	Optional	1..5	PNR / MANIFEST	Operational context; not Journey core unless needed
baggageInfo	string / object	Optional	source-defined	PNR / MANIFEST	Source-specific operational context
ssrCodes	array<string>	Optional	IATA SSR codes	PNR	Sensitive / booking-service context — store only if needed and governed
manualReason	string	Optional	1..500	MANUAL	Reason for manual correction or creation
createdBy	string	Optional	user / service identifier	TIS / MANUAL	Useful for manual snapshots and operational audit

Source resolution

The Journey is built by merging accepted JourneySourceSnapshot records from upstream sources. TIS decides whether to accept a snapshot based on:

• sourceSystem authority for the affected field (see matrix below)
• effectiveAtTimeStamp versus the Journey's current state
• changeType (INITIAL, UPDATE, CANCELLED, CORRECTION)

Latest accepted source snapshot wins, with the contribution matrix below as the precedence guide. MANUAL snapshots always carry an explicit manualReason and override automated sources when accepted — they exist precisely for cases where automated data is wrong.

Source contribution matrix

Which source can authoritatively update which Journey field.

Journey field	API	PNR	MANIFEST	MANUAL	Recommendation
travelerId	Yes	Maybe	Yes	Yes	API strongest for identity / document matching; PNR weaker unless passenger identity is reliable
transportType	Maybe	Yes	Yes	Yes	Manifest usually strongest operational source
operatorCode	Maybe	Yes	Yes	Yes	Latest accepted source can update
conveyanceNumber	Maybe	Yes	Yes	Yes	Manifest may be authoritative near departure
routeFrom	Maybe	Yes	Yes	Yes	PNR has itinerary; manifest has operational movement
routeTo	Maybe	Yes	Yes	Yes	As above
scheduledDeparture	Maybe	Yes	Yes	Yes	Manifest / carrier feed likely strongest near operation
scheduledArrival	Maybe	Yes	Yes	Yes	As above
journeyStatus	No	Maybe	Yes	Yes	TIS owns final lifecycle, derived from source events
version	No	No	No	No	TIS-owned
currentSnapshotId	No	No	No	No	TIS-owned

Yes — source is authoritative for this field. Maybe — source may update if no stronger source has contributed recently. No — source cannot update this field.

See also

• Data Model overview — full entity set, standards alignment, domain separation
• Traveler — the entity Journeys are linked to
• Encounter — Journeys and Encounters are independent dimensions of the Traveler; correlation between them is derived