Skip to content

Data Model Transit

mavrovde edited this page Nov 1, 2026 · 1 revision

Data Model: Transit

Part of the Data Model. A logical model for the API's read side, not a copy of any physical schema; storage names may differ. Conventions, the record envelope and retention classes: Data Model section 5. API side: Endpoints, Public Transport and Accessibility.

The domain holds public transport: stop places and their platforms, lines and their operators, the timetable as journeys with scheduled calls, live call observations (expected times, platform changes, cancellations), service alerts and published punctuality figures. A departure in the API is a scheduled call joined with its newest call observation.

1. Diagram

erDiagram
  stop_place |o--o{ stop_place : "contains"
  stop_place ||--o{ stop_point : "contains"
  transit_operator ||--o{ transit_line : "operates"
  transit_line ||--o{ journey : "runs"
  journey ||--|{ scheduled_call : "calls at"
  stop_point ||--o{ scheduled_call : "is served by"
  scheduled_call ||--o{ call_observation : "is updated by"
  service_alert ||--|{ alert_scope : "affects"
  transit_line |o--o{ alert_scope : "is named in"
  stop_place |o--o{ alert_scope : "is named in"
  admin_region ||--o{ punctuality_figure : "is measured by"
  source ||--o{ stop_place : "describes"
  source ||--o{ journey : "describes"
  source ||--o{ call_observation : "describes"
  source ||--o{ service_alert : "describes"
  stop_place {
    string stop_place_id PK
    string name
    point location
    string national_stop_code
    string parent_id FK
    string region_code FK
    string source_ref FK
  }
  stop_point {
    string stop_point_id PK
    string stop_place_id FK
    string platform_label
    point location
  }
  transit_operator {
    string operator_id PK
    string name
  }
  transit_line {
    string line_id PK
    string operator_id FK
    string line_name
    string transport_mode
  }
  journey {
    string journey_id PK
    string line_id FK
    date service_date
    string destination_label
    string source_ref FK
  }
  scheduled_call {
    string journey_id FK
    int call_order
    string stop_point_id FK
    instant planned_arrival_at
    instant planned_departure_at
    string planned_platform
  }
  call_observation {
    string journey_id FK
    int call_order
    instant observed_at
    instant expected_arrival_at
    instant expected_departure_at
    string expected_platform
    string call_status
    string source_ref FK
  }
  service_alert {
    string alert_id PK
    string alert_severity
    string cause
    string effect
    instant valid_from
    instant valid_to
    string headline
    string description
    string text_lang
    string source_ref FK
  }
  alert_scope {
    string alert_id FK
    string scope_kind
    string line_id FK
    string stop_place_id FK
    string transport_mode
  }
  punctuality_figure {
    string region_code FK
    instant period_from
    instant period_to
    decimal on_time_share_pct
    string source_ref FK
  }
Loading

2. Network

stop_place

A station or stop as a traveller names it ("Köln Hbf"). Stop places can nest (a large station and its bus terminal). Retention REF.

Field Type Req Unit / format Constraints and values Description API field
stop_place_id id yes Identity id (sp_…), stopPlace.id
name text yes Name as published name, stopPlace.name
location point yes WGS 84 Representative point location, distanceM
national_stop_code key no the national stop identifier format The national identifier, where published globalId
parent_id id → stop_place no not self Enclosing stop place none; search returns the outermost
region_code key → admin_region no Enclosing region region
modes list<enum<transport_mode>> yes may be empty Modes served, derived from the lines calling modes[], modes filter
search_fold text yes folded Name search key none (storage-only)
envelope sourceFamily

stop_point

A platform, track or bay inside a stop place, where vehicles actually call. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
stop_point_id id yes Identity none
stop_place_id id → stop_place yes Owning stop place departures grouping
platform_label text no as signed Platform or track platform.planned fallback
location point no WGS 84 Position none

transit_operator

A transport operator. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
operator_id id yes Identity none
name text yes Name as published line.operator

transit_line

A line as passengers know it ("RE 1", "U3", "Bus 132"). Retention REF.

Field Type Req Unit / format Constraints and values Description API field
line_id id yes Identity none
operator_id id → transit_operator no Operator line.operator
line_name text yes Public name line.name, line filter, affected.lines[]
transport_mode enum<transport_mode> yes see dictionary Mode line.mode, modes filter

3. Timetable and live state

journey

One run of a line on one service day. Retention OBS for past service days, REF for the current timetable window.

Field Type Req Unit / format Constraints and values Description API field
journey_id id yes Identity none
line_id id → transit_line yes Line line
service_date date yes Europe/Berlin Operating day; calls may fall after midnight of it none
destination_label text no Headsign destination
extra bool yes True for a run not in the published timetable status: extra
envelope sourceFamily

scheduled_call

One planned stop of a journey. Retention follows the journey.

Field Type Req Unit / format Constraints and values Description API field
journey_id id → journey yes The journey none
call_order int yes ≥ 0, increasing along the journey Position in the journey ordering
stop_point_id id → stop_point yes Where it calls stopPlace
planned_arrival_at instant no UTC null at the first call Planned arrival none in v1
planned_departure_at instant no UTC null at the last call Planned departure planned
planned_platform text no Planned platform platform.planned

call_observation

One live update of one call. Retention OBS. The current state of a call is its newest observation; a call without one has no real-time information (realtime: false).

Field Type Req Unit / format Constraints and values Description API field
journey_id, call_order → scheduled_call yes The call none
observed_at instant yes UTC When the update was published or observed freshness
expected_arrival_at instant no UTC Expected arrival none in v1
expected_departure_at instant no UTC Expected departure expected, input of delayMin
expected_platform text no null when unchanged Changed platform platform.expected
call_status enum<call_status> yes scheduled, cancelled, extra, unknown Published status of the call status (with the domain rule for on_time and delayed)
source_ref key → source yes Source of the update sourceFamily

delayMin is not stored: it is expected − planned in whole minutes by the documented rounding (FR-TRANSIT-003). on_time and delayed are derived from it by a documented threshold.

4. Alerts and punctuality

service_alert

A published disruption notice. Retention: event record; versions kept as observations (OBS); ended alerts leave the read side after a configurable grace period (TRN).

Field Type Req Unit / format Constraints and values Description API field
alert_id id yes Identity id (ds_…), disruptionIds[]
alert_severity enum<alert_severity> yes info, minor, major, severe Severity severity, severity filter
cause enum<alert_cause> no see dictionary Cause cause
effect enum<alert_effect> yes no_service, reduced_service, significant_delays, detour, stop_moved, other Effect effect
valid_from instant yes UTC Start of validity validity.from, active_at filter
valid_to instant no UTC null = open-ended End of validity validity.until
headline ltext yes plain text Title headline
description ltext no plain text Text description
text_lang text yes BCP 47 Original language textLanguage
envelope updatedAt, sourceFamily

alert_scope

What an alert affects: a line, a stop place, a mode or a region. Retention follows the alert.

Field Type Req Unit / format Constraints and values Description API field
alert_id id → service_alert yes The alert none
scope_kind enum<scope_kind> yes line, stop_place, mode, region What the row names which list it fills
line_id id → transit_line no set when scope_kind = line Affected line affected.lines[]
stop_place_id id → stop_place no set when scope_kind = stop_place Affected stop place affected.stopPlaces[], stop disruptions
transport_mode enum<transport_mode> no set when scope_kind = mode Affected mode affected.modes[]
region_code key → admin_region no set when scope_kind = region Affected region area disruptions

punctuality_figure

A punctuality figure as a publisher states it for a region and a period. The API passes it on and computes none of its own (FR-TRANSIT-007). Retention OBS.

Field Type Req Unit / format Constraints and values Description API field
region_code key → admin_region yes Region punctuality.region
period_from, period_to instant yes UTC period_from < period_to Period punctuality.periodFrom, periodUntil
on_time_share_pct decimal(5,2) yes % 0 to 100 Share on time, as published punctuality.onTimeSharePct
source_ref key → source yes Publisher's source sourceFamily

5. Keys and relationships

Relationship Cardinality Rule
stop_place → parent many to zero-or-one One level of nesting is typical
stop_place → stop_point one to many
transit_line → journey → scheduled_call one to many, one to one-or-more A journey has at least two calls
scheduled_call → call_observation one to many Keyed by journey_id and call_order
service_alert → alert_scope one to one-or-more

Timetable and live updates of one region share one natural key space within their source; a live update is matched to its scheduled call by the publisher's journey key and call order within that source.

6. Temporal behaviour

  • Network entities are REF. The timetable is held for a window around now; past service days fall to OBS.
  • A planned call time may lie after midnight of its service date; instants are stored, so no time-of-day arithmetic leaks to the API.
  • Cancelled calls stay with call_status = cancelled (FR-TRANSIT-004).

7. Access paths

Path Used by
Text search on the stop place's fold, or nearest stop places to a point search stop places
Calls of all stop points of a stop place inside a bounded time window, ordered by expected or planned time, with the newest observation each departures
Active alerts by stop_place_id through alert_scope, or by area disruptions
Newest figure per region data.punctuality

8. Licence and attribution

Timetable, live updates and alerts may come from different sources; each record names its own. Share-alike transit records carry the share-alike flag and offer.

9. Entity to API

Entity Operations Resource members
stop_place, stop_point GET /v1/stop-places, path {stopPlaceId} stop place item, stopPlace
transit_line, transit_operator, journey, scheduled_call, call_observation GET /v1/stop-places/{stopPlaceId}/departures departure item
service_alert, alert_scope GET /v1/stop-places/{stopPlaceId}/disruptions, GET /v1/disruptions disruption item
punctuality_figure GET /v1/disruptions data.punctuality

Field-level mapping: Mapping.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally