Repository navigation
Data Model Mapping
Part of the Data Model. This page traces every public field of the API to the logical fields it is made of. It shows that the API is domain-shaped: one resource composes several entities, one entity serves several resources, and some public fields are computed by domain rules rather than read.
The logical model is not the physical schema; the read contract maps physical columns to these logical fields, and the storage adapter maps logical fields to the public shape (Domain Model, anti-corruption layer).
flowchart LR
ST[(Physical storage<br/>private)] -- read contract --> LM[Logical read model<br/>entities and fields]
LM -- storage adapter --> DO[Domain objects<br/>aggregates and rules]
DO -- HTTP adapter --> PU[Public payload<br/>JSON and GeoJSON]
R[Domain rules<br/>lamp, delay, step-free, trend] --> DO
These logical fields exist for identity, matching and bookkeeping. No public field is made from them (DM-018):
| Field | Where | Why it stays inside |
|---|---|---|
surrogate ids (*_id) |
every entity | Public ids are an opaque encoding of them (CONV-010), never the raw value |
origin_key |
record envelope | A publisher's key is meaningful only inside its source |
recorded_at |
record envelope | Storage bookkeeping |
withdrawn_at |
record envelope | Drives visibility only |
version_no |
traffic_event_observation |
Internal version counter |
search_fold, street_fold, number_fold
|
Places, Transit | Search keys |
prominence |
place |
Ordering input only |
primary_event_id |
traffic_event |
Duplicate folding; visible only as extra attribution |
owner_entity, owner_id, field
|
text_variant |
Link bookkeeping |
freshness_version |
source_freshness |
Only as an input of the opaque ETag
|
review_signed_on |
source |
Gate input |
| API field | Logical source | Kind |
|---|---|---|
place id
|
place.place_id |
encoded |
place name
|
place.name (or place_alias.label in the response language) |
read |
place kind
|
place.place_kind |
mapped code |
place region
|
admin_region tree above place.region_code
|
composed |
place location
|
place.location |
read |
place bbox
|
envelope of place.extent
|
computed |
place matchedOn
|
place_alias.name_kind of the matching name |
mapped code |
place sourceFamily
|
place.source_ref |
read |
address id
|
address.address_id |
encoded |
address address.*
|
address.street, house_number, postcode, locality, region_code
|
read |
address matchQuality
|
match of the query against street_fold, number_fold, locality
|
rule |
point of interest category, name, location, openingHours
|
point_of_interest.category, name, location, opening_hours_text
|
read |
distanceM (any item) |
the item's location and the query point |
computed |
describe nearestAddress
|
nearest address
|
composed |
describe nearestJunction
|
nearest junction
|
composed |
| API field | Logical source | Kind |
|---|---|---|
situation id
|
traffic_event.event_id |
encoded |
kind, severity, direction
|
traffic_event.event_kind, severity, direction
|
mapped code |
directionText |
traffic_event.direction_label |
read |
position.fromKm, toKm
|
traffic_event.from_km, to_km
|
read |
position.junctionFrom, junctionTo
|
junction.name via from_junction_id, to_junction_id
|
composed |
location, geometry
|
traffic_event.location, shape and event_extent.shape
|
read, simplified per geometry=
|
validity.from, until (and …Local) |
traffic_event.valid_from, valid_to
|
read, rendered |
lanes.closed, lanes.total
|
traffic_event.lanes_closed, lanes_total
|
read |
delayMin, lengthM
|
traffic_event.delay_min, affected_length_m
|
read |
headline, description, textLanguage
|
traffic_event.headline, description, text_lang, text_variant
|
read, localised |
updatedAt |
traffic_event.changed_at |
read |
sourceFamily, meta.attribution[]
|
traffic_event.source_ref and those of its duplicates |
composed |
distanceAheadKm |
chainage of the event and the snapped point | computed |
corridor lamp, lampReason
|
active events of the corridor | rule (FR-ROAD-004) |
motorway road, name, states[]
|
road.road_ref, name, states
|
read |
motorway situations.total, byKind
|
active traffic_event rows of the road |
computed |
history item, observedAt
|
traffic_event_observation.*, observed_at
|
read |
| API field | Logical source | Kind |
|---|---|---|
refuel id, name, brand, address, location
|
fuel_station.* |
encoded, read |
openingState |
fuel_station.open_state |
mapped code |
offers[].product, unit
|
fuel_product.product_code, price_unit
|
read |
offers[].price |
fuel_price_observation.price, currency (newest per product) |
read |
offers[].observedAt |
fuel_price_observation.observed_at |
read |
distanceAlongKm, detourM
|
the item's location and the corridor |
computed |
charging id, name, operator, access, location
|
charging_site.* |
encoded, read |
summary.chargePoints |
count of charge_point
|
computed |
summary.maxPowerKw |
maximum of charge_point.power_max_kw
|
computed |
summary.availableNow |
count of points whose newest state is available and fresh, null when none has a fresh state |
rule |
chargePoints[].id |
charge_point.point_id |
encoded |
connectors[].type, maxPowerKw
|
connector.connector_type, power_max_kw
|
mapped code, read |
availability.state, observedAt
|
newest charge_point_state_observation
|
read |
meta.notes.purpose[] |
source_note of the price source |
read |
| API field | Logical source | Kind |
|---|---|---|
parking id, name, kind, location
|
parking_facility.* |
encoded, mapped, read |
vehicleClasses[] |
facility_capacity.vehicle_class |
composed |
capacity.total, byVehicle
|
facility_capacity.total_spaces |
composed |
occupancy.free, state, observedAt
|
newest occupancy_observation
|
read |
occupancy.trend |
recent occupancy_observation rows |
rule |
termsRequired |
parking_facility.acceptance_required and the key's recorded acceptance |
rule |
sharing id, name, operator, location
|
sharing_station.* |
encoded, read |
vehiclesAvailable |
newest sharing_availability_observation
|
read |
| API field | Logical source | Kind |
|---|---|---|
stop place id, name, location, globalId, region
|
stop_place.*, national_stop_code, admin_region
|
encoded, read, composed |
stop place modes[]
|
stop_place.modes |
mapped code |
departure line.name, mode, operator
|
transit_line.line_name, transport_mode, transit_operator.name
|
read, mapped |
destination |
journey.destination_label |
read |
planned |
scheduled_call.planned_departure_at |
read, rendered |
expected |
newest call_observation.expected_departure_at
|
read, rendered |
realtime |
whether a call_observation exists |
computed |
delayMin |
expected − planned |
rule (FR-TRANSIT-003) |
platform.planned, expected
|
scheduled_call.planned_platform, call_observation.expected_platform
|
read |
status |
call_observation.call_status, journey.extra and delayMin
|
rule |
disruptionIds[] |
alert_scope rows naming the line or stop place |
composed |
| disruption fields |
service_alert.*, alert_scope.*
|
encoded, mapped, read |
data.punctuality |
punctuality_figure.* |
read |
facility id, kind, description, state, stateSince, observedAt, expectedBack
|
station_facility.facility_id, facility_kind, position_text, facility_status, status_changed_at, status_observed_at, expected_back_at
|
encoded, mapped, read |
stepFreeAccess |
step_free_path, path_facility, current facility states |
rule (FR-ACCESS-002) |
| API field | Logical source | Kind |
|---|---|---|
warning id, hazard, level, levelName, issuer
|
weather_warning.warning_id, hazard, warning_level, level_label, issuer_name
|
encoded, mapped, read |
headline, description, instruction, textLanguage, originalLanguage
|
weather_warning texts, text_lang, text_variant
|
read, localised |
validity |
weather_warning.valid_from, valid_to
|
read, rendered |
area.name, area.geometry
|
warning_area.area_name, boundary via warning_coverage
|
composed |
distanceAlongKm |
area and corridor | computed |
roadWeather[] |
road_weather_station.location, newest road_weather_observation
|
composed |
weather lamp
|
active warning levels | rule |
| API field | Logical source | Kind |
|---|---|---|
sourceFamily (any item) |
the record's source_ref
|
read |
meta.attribution[] |
source, publisher, licence of every contributing record |
composed |
meta.notes |
source_note of every contributing source |
composed |
meta.freshness[], meta.asOf
|
source_freshness and source.stale_after_s
|
computed |
ETag |
source_freshness.freshness_version of every source read plus the normalised query |
computed |
/v1/sources entries |
source, publisher, licence, source_note
|
composed |
driving rules topic, title, rules[], reviewedOn
|
rule_topic, rule_statement
|
read |
| ID | Requirement | Verification |
|---|---|---|
| DM-018 | No public field MUST be made from a storage-only field of section 1 (surrogate ids in raw form, natural keys, row bookkeeping, search keys, link bookkeeping); public ids MUST be opaque encodings. | Lint |
| DM-019 | Every public field of every operation MUST trace to at least one logical field or to a documented domain rule on this page; a field without a trace MUST NOT ship. | Review |
| DM-020 | Derived values (lamps, delayMin, stepFreeAccess, occupancy.trend, summary.availableNow, distances) MUST be computed by documented domain rules and MUST NOT be stored in the read model. |
Unit |
| DM-021 | A change to the logical model MUST update this mapping and the [[Data Dictionary | Data-Dictionary]] in the same change, and MUST follow the contract versioning of [[Data Model |
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