Skip to content

Data Model Mapping

mavrovde edited this page Nov 1, 2026 · 1 revision

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
Loading

1. The rule: storage-only fields never reach a payload

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

2. Places

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

3. Roads

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

4. Energy

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

5. Parking

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

6. Transit and accessibility

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)

7. Weather

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

8. Envelope and service

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

9. Requirements

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally