Repository navigation
Data Model
Part of the Technical Specification. Requirement prefix: DM. This page and its eight domain pages describe the logical read model: the storage contract the API reads, written as logical entities and fields. It is the substance behind the read contract and the source of every fact in a payload of the Resource Model.
This is a logical model for the API's read side, not a copy of any physical schema. Entity and field names on these pages were chosen for this documentation. The platform's storage may use other names, split an entity over several stores or keep several entities in one; the read contract maps them. Nothing here describes how the data is obtained or how storage is operated.
| In scope | Out of scope |
|---|---|
| Every entity and field the API reads to answer an operation | Physical tables, views, roles, partitions and their names |
| Keys, relationships, nullability and code lists | How data reaches storage, and anything about that process |
| Temporal behaviour and retention classes, as design rules | Real durations, volumes, sizes, rates or coverage |
| The licence and attribution linkage of every record | The API's own access store (keys, plans, usage, audit): see [[Data Governance |
| Logical access paths (how a question finds its rows) | Index definitions and query plans |
The model follows the bounded contexts of the Domain Model: the domain pages are the bounded contexts, and the aggregates there are the entities here plus the domain rules of the API. The API composes entities into domain-shaped answers; it never mirrors one entity as one resource (Mapping).
| Page | Entities | Serves the operations |
|---|---|---|
| [[Places | Data-Model-Places]] |
place, place_alias, admin_region, address, point_of_interest
|
| [[Roads | Data-Model-Roads]] |
road, junction, traffic_event, event_extent, traffic_event_observation
|
| [[Energy | Data-Model-Energy]] |
fuel_station, opening_period, fuel_product, fuel_price_observation, charging_site, charge_point, connector, charge_point_state_observation
|
| [[Parking | Data-Model-Parking]] |
parking_facility, facility_capacity, occupancy_observation, sharing_station, sharing_availability_observation
|
| [[Transit | Data-Model-Transit]] |
stop_place, stop_point, transit_operator, transit_line, journey, scheduled_call, call_observation, service_alert, alert_scope, punctuality_figure
|
| [[Accessibility | Data-Model-Accessibility]] |
station_facility, facility_state_observation, step_free_path, path_facility
|
| [[Weather | Data-Model-Weather]] |
weather_warning, warning_area, warning_coverage, road_weather_station, road_weather_observation
|
| [[Provenance | Data-Model-Provenance]] |
publisher, licence, source, source_note, source_freshness, text_variant
|
| [[Mapping | Data-Model-Mapping]] | |
| [[Data Dictionary | Data-Dictionary]] |
Curated reference content (the driving rules) is described in section 9 of this page.
flowchart TD
subgraph REF[Reference]
PL[Places<br/>place, address, point of interest]
RD[Road network<br/>road, junction]
end
subgraph LIVE[Current state and observations]
TE[Roads<br/>traffic events]
EN[Energy<br/>fuel, charging]
PK[Parking<br/>facilities, occupancy, sharing]
TR[Transit<br/>stops, calls, alerts]
AC[Accessibility<br/>station facilities]
WE[Weather<br/>warnings, road weather]
end
PV[(Provenance<br/>source, licence, publisher,<br/>freshness, text variants)]
PL --> TE & EN & PK & TR & WE
RD --> TE & PK & WE
TR --> AC
PV -. every record .-> REF & LIVE
- Places and the road network are reference data: every other domain locates itself by a point, a region or a road reference.
- Provenance is a shared kernel: every record of every entity names its source, and through it its publisher and licence.
- Accessibility hangs off Transit: a station facility belongs to a stop place.
The overview shows the main entities and their relationships across domains. Attributes are on the domain pages.
erDiagram
source ||--o{ place : "describes"
source ||--o{ traffic_event : "describes"
source ||--o{ fuel_station : "describes"
source ||--o{ charging_site : "describes"
source ||--o{ parking_facility : "describes"
source ||--o{ stop_place : "describes"
source ||--o{ weather_warning : "describes"
licence ||--o{ source : "governs"
publisher ||--o{ source : "publishes"
admin_region ||--o{ place : "contains"
place ||--o{ place_alias : "is called"
road ||--o{ junction : "has"
road |o--o{ traffic_event : "carries"
traffic_event ||--o{ traffic_event_observation : "was observed as"
fuel_station ||--o{ fuel_price_observation : "is priced by"
fuel_product ||--o{ fuel_price_observation : "prices"
charging_site ||--|{ charge_point : "groups"
charge_point ||--|{ connector : "offers"
charge_point ||--o{ charge_point_state_observation : "reports"
parking_facility ||--o{ occupancy_observation : "reports"
road |o--o{ parking_facility : "serves"
stop_place ||--o{ stop_point : "contains"
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"
stop_place ||--o{ station_facility : "equips"
station_facility ||--o{ facility_state_observation : "reports"
weather_warning ||--|{ warning_coverage : "covers"
warning_area ||--o{ warning_coverage : "is covered by"
| Type | Meaning |
|---|---|
id |
A stable, opaque identifier chosen by the platform. Never derived from a storage key, a source name or a publisher's key in a way a client could reverse. |
key |
A natural key as the publisher writes it, unique only within its source |
text |
A UTF-8 string, plain text, no markup |
ltext |
A localisable text: the original as published plus optional text_variant rows in other languages ([[Provenance |
int |
A whole number |
decimal(p,s) |
An exact decimal with precision p and scale s; never binary floating point |
bool |
A two-valued fact that is always known; a fact that can be unknown is an enum with unknown
|
enum<name> |
A value from a closed code list in storage (listed on the [[Data Dictionary |
instant |
A point on the UTC time line, at least second precision |
date |
A calendar date, interpreted in Europe/Berlin |
time |
A local wall-clock time of day, Europe/Berlin |
point, line, polygon, geometry
|
WGS 84 geometry (SRID 4326): a point, a line string or multi-line, a polygon or multi-polygon, or any of these |
list<T> |
An ordered list of T
|
currency |
An ISO 4217 alphabetic code |
- Every instant is stored in UTC. The Europe/Berlin rendering (
…Localin the API, CONV-004) is computed at the edge, never stored. -
Validity is a half-open interval
[valid_from, valid_to).valid_tonull means open-ended or not published; a publisher's far-future placeholder date is read as open-ended. -
observed_atis the instant a live state was true according to its source, the observation instant every live value carries (FR-GEN-004). -
published_atis the publisher's own timestamp for the record, null when the publisher gives none. It is never replaced by any other clock. -
changed_atis when the content of a record last differed from its previous version.
- Geometry is WGS 84 (SRID 4326), longitude before latitude in storage and in GeoJSON,
{lat, lon}in JSON (CONV-008). - Every located entity has one representative point (
location), used for distance and nearest-neighbour questions, and optionally a shape (geometryorboundary), used for intersection and corridor questions. - Distances are geodesic metres. Road positions (chainage) are kilometres as signed on the road.
A dimensioned field carries its unit as a name suffix: _m metres, _km kilometres, _kw kilowatts, _min minutes, _s seconds, _c degrees Celsius, _pct percent. Prices are a decimal amount with a currency and a per-unit basis (litre, kilogram, kilowatt-hour) stated by the product or field.
An amount is decimal(6,3) for fuel prices (three decimals as published) with an ISO 4217 currency (always EUR today). Comparison and ordering are exact. Prices include VAT as published.
- Each entity has a surrogate id (
<entity>_id), stable for the life of the record. The API's public ids (pl_…,rs_…, CONV-010) are derived from it by an opaque, reversible-only-by-the-service encoding. - Each record from a source also has a natural key (
origin_key), unique only together with itssource_ref. Two publishers may use the same key for different things; a key is never compared across sources. - Reference codes from public standards (ISO 3166-2 region codes, the official municipal key, the national stop identifier, the EVSE identifier) are stored as published and may be returned as such.
- Required fields are never null. Optional fields are null when the source does not publish the fact or the fact is unknown.
- A missing value is never filled with a default: an unpublished count is null, never
0(ENV-041). An empty list means known to be none.
| Kind | Behaviour | Examples |
|---|---|---|
| Reference record | Describes a thing that exists; updated in place when the publisher changes it; soft-closed when withdrawn | place, road, fuel station, charging site, stop place |
| Current-state record | The latest known state of a thing, replaced by each newer state | the open state of a fuel station, the state of a facility |
| Observation | One state at one observed_at; append-only, never updated |
fuel price, charge-point state, occupancy, call update, road weather |
| Event record | A situation with validity, versioned; each version is also kept as an observation | traffic event, service alert, weather warning |
The current state of a thing is either the newest observation or a current-state field kept in step with it; both forms must agree.
- A record its publisher stops publishing is soft-closed:
withdrawn_atis set, the record is kept, and reads exclude it unless an operation states otherwise (for example an ended situation that still answers forroads.ended_retention_h, FR-ROAD situation lookup). - A record found to be wrong (a duplicate, a misreading) is corrected: it disappears from the read side at once. Corrected records are never visible to the API.
Every entity in this model, except pure link entities, carries these fields. Domain pages list only their own fields and refer here.
| Field | Type | Req | Description | API field |
|---|---|---|---|---|
source_ref |
key → source
|
yes | The source family the record comes from |
sourceFamily, meta.attribution[], meta.freshness[]
|
origin_key |
key |
yes on reference and event records | The publisher's own key for the record, unique within source_ref
|
none (storage-only) |
published_at |
instant |
no | The publisher's timestamp for this version |
updatedAt where no changed_at exists |
recorded_at |
instant |
yes | When this version became valid in the read side | none (storage-only) |
changed_at |
instant |
yes on reference and event records | When the content last differed | updatedAt |
withdrawn_at |
instant |
no | When the publisher stopped publishing the record (soft close) | none; drives visibility |
Code lists are closed in storage (a value outside the list is refused or mapped to other before it is stored) and open in the API (ENV-050). Every stored code maps to exactly one API value; the Data Dictionary lists both.
| Class | Applies to | Rule |
|---|---|---|
REF |
Reference records | Kept while published; kept after soft close for as long as an id the API returned may still be resolved (FR-PLACE-004) |
CUR |
Current-state records | Replaced in place; only the newest state is held |
OBS |
Observations and event versions | Append-only; kept for a configurable horizon; the API reads them only inside a bounded window and the plan's history depth (FR-ROAD-008) |
TRN |
Ended events | Readable for a configurable grace period after valid_to (roads.ended_retention_h for situations), then out of the read side |
Durations are configuration of the platform, not part of this model. Where a source's terms limit how long its data may be kept, the shorter limit applies (LIC-011).
Each record names one source; the source names one licence and one publisher. A response's meta.attribution[] is the set of sources of the records it used (Provenance). Records under a share-alike licence are never combined with records of another licence into one stored record (LIC-012).
| Path | Question | Served by |
|---|---|---|
| Nearest | "What is near this point?" | a spatial index on location, filtered by radius, ordered by distance |
| Within | "What is inside this box or area?" | a spatial index on location or geometry, bounded by area |
| Intersecting | "Which areas contain this point or touch this corridor?" | a spatial index on boundary or geometry
|
| Along a corridor | "What lies along this road section or route?" | road reference plus chainage range, or a buffered line tested against each point's box |
| By place | "What is in this place?" | the place's representative point and extent, then nearest or within |
| By key | "This one record" | the surrogate id |
| By time window | "What was observed between t1 and t2?" |
observed_at range, bounded by configuration |
| Newest per thing | "Current state of each charge point" | the newest observation per thing inside a freshness horizon |
| Text search | "Places called Koln" | a folded (case- and diacritic-insensitive) search key |
Every path is bounded by configuration (radius, area, corridor length, window, page size), so no question reads an unbounded set.
| ID | Requirement | Verification |
|---|---|---|
| DM-001 | The read side MUST be documented as this logical model; the read contract MUST map every contract column to a logical field on these pages, and storage names MUST NOT appear on them. | Review |
| DM-002 | Every instant MUST be stored in UTC; local renderings MUST be computed at the edge and MUST NOT be stored. | Contract |
| DM-003 | Every geometry MUST be WGS 84 (SRID 4326); every located entity MUST have exactly one representative point. | Contract |
| DM-004 | Every dimensioned field MUST carry its unit as a name suffix from section 5.4. | Lint |
| DM-005 | Monetary amounts MUST be exact decimals with an ISO 4217 currency; binary floating point MUST NOT hold money at any point. | Unit |
| DM-006 | Every entity MUST have a stable surrogate id; natural keys MUST be unique only together with their source and MUST NOT be compared across sources. | Mapping |
| DM-007 | A field the source does not publish MUST be null; it MUST NOT be filled with a default or inferred from another field. | Mapping |
| DM-008 | Validity MUST be the half-open interval [valid_from, valid_to) with null valid_to as open-ended; published_at MUST be the publisher's stamp or null, never another clock. |
Unit |
| DM-009 | Observations MUST be append-only: an observation MUST NOT be updated or deleted inside its retention class. | Review |
| DM-010 | A withdrawn record MUST be soft-closed with withdrawn_at and kept for its retention class; reads MUST exclude it unless the operation's specification says otherwise. |
Handler |
| DM-011 | Every record MUST carry exactly one source_ref, and through it one licence and one publisher. |
Contract |
| DM-012 | Records under a share-alike licence MUST NOT be combined with records under another licence in one stored record. | Mapping |
| DM-013 | Every code list MUST be closed in storage, and every stored code MUST map to one API value or to other. |
Mapping |
| DM-014 | Every entity MUST declare one retention class from section 5.12; durations MUST be configuration, and a source's retention limit MUST take precedence. | Review |
| DM-015 | Every access path an operation uses MUST be bounded by configuration and served by an indexable path from section 6. | Load |
| DM-016 | The read side MUST expose, per source, the instant of its newest data and a version that changes when that data changes. | Contract |
| DM-017 | A corrected record MUST be invisible to the read side from the moment of correction. | Contract |
Requirements DM-018 to DM-021 are on Mapping.
The logical model changes with the read contract (Architecture Overview, "Keeping the API independent of platform storage"): a new entity, field or code is a minor contract version; a removed or retyped field is a new major contract version beside the old one. A storage rename changes neither this model nor any payload.
The driving rules are curated text, not data from a publisher.
erDiagram
rule_topic ||--|{ rule_statement : "contains"
rule_topic {
string topic_code PK
string title
date reviewed_on
}
rule_statement {
string statement_id PK
string topic_code FK
int position
string body
string legal_basis
}
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
topic_code |
enum<rule_topic> |
yes | see [[Data Dictionary | Data-Dictionary]] | The topic | |
title |
ltext |
yes | Title of the topic | title |
||
reviewed_on |
date |
yes | ISO date | not in the future | When the text was last reviewed | reviewedOn |
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
statement_id |
id |
yes | Identity | none | ||
topic_code |
enum<rule_topic> |
yes | FK rule_topic
|
Owning topic | none | |
position |
int |
yes | ≥ 1, unique per topic | Order within the topic | array order | |
body |
ltext |
yes | The rule | rules[].text |
||
vehicle_classes |
list<enum<vehicle_class>> |
yes | non-empty | Vehicles the rule applies to | rules[].appliesTo |
|
legal_basis |
text |
no | The legal reference | rules[].legalBasis |
Retention class REF. The disclaimer is a fixed text of the API, not data.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference