Skip to content

Data Model

mavrovde edited this page Nov 1, 2026 · 1 revision

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.

1. Purpose and scope

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).

2. Pages

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.

3. Domain map

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
Loading
  • 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.

4. Overview diagram

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"
Loading

5. Conventions

5.1 Logical types

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

5.2 Time

  • Every instant is stored in UTC. The Europe/Berlin rendering (…Local in the API, CONV-004) is computed at the edge, never stored.
  • Validity is a half-open interval [valid_from, valid_to). valid_to null means open-ended or not published; a publisher's far-future placeholder date is read as open-ended.
  • observed_at is the instant a live state was true according to its source, the observation instant every live value carries (FR-GEN-004).
  • published_at is the publisher's own timestamp for the record, null when the publisher gives none. It is never replaced by any other clock.
  • changed_at is when the content of a record last differed from its previous version.

5.3 Space

  • 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 (geometry or boundary), used for intersection and corridor questions.
  • Distances are geodesic metres. Road positions (chainage) are kilometres as signed on the road.

5.4 Units

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.

5.5 Money

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.

5.6 Identifiers and keys

  • 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 its source_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.

5.7 Nullability

  • 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.

5.8 Observations and current state

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.

5.9 Soft close and correction

  • A record its publisher stops publishing is soft-closed: withdrawn_at is set, the record is kept, and reads exclude it unless an operation states otherwise (for example an ended situation that still answers for roads.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.

5.10 The record envelope

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

5.11 Code lists

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.

5.12 Retention classes

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).

5.13 Licence and attribution

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).

6. Logical access paths

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.

7. Requirements

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.

8. Change rules

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.

9. Curated reference content

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
  }
Loading

rule_topic

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

rule_statement

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally