Skip to content

Data Model Roads

mavrovde edited this page Nov 1, 2026 · 1 revision

Data Model: Roads

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, Roads.

The domain holds the road network the API can speak about (roads and their junctions) and the traffic events on it: closures, roadworks, jams, accidents, hazards, restrictions and weather effects. The API calls a traffic event, as served, a road situation.

1. Diagram

erDiagram
  road ||--o{ junction : "has"
  road |o--o{ traffic_event : "carries"
  junction |o--o{ traffic_event : "bounds"
  traffic_event ||--o{ event_extent : "spans"
  traffic_event ||--o{ traffic_event_observation : "was observed as"
  traffic_event |o--o{ traffic_event : "duplicates"
  source ||--o{ traffic_event : "describes"
  road {
    string road_ref PK
    string road_class
    string name
    decimal length_km
    line geometry
  }
  junction {
    string junction_id PK
    string road_ref FK
    string number
    string name
    string junction_kind
    decimal chainage_km
    point location
  }
  traffic_event {
    string event_id PK
    string event_kind
    string severity
    string road_ref FK
    string road_class
    string direction
    string direction_label
    decimal from_km
    decimal to_km
    string from_junction_id FK
    string to_junction_id FK
    point location
    geometry shape
    instant valid_from
    instant valid_to
    int lanes_closed
    int lanes_total
    int delay_min
    int affected_length_m
    string headline
    string description
    string text_lang
    string primary_event_id FK
    string source_ref FK
  }
  event_extent {
    string event_id FK
    int position
    string road_ref FK
    decimal from_km
    decimal to_km
    geometry shape
  }
  traffic_event_observation {
    string event_id FK
    instant observed_at
    int version_no
    string event_kind
    string severity
    instant valid_from
    instant valid_to
    int lanes_closed
    int delay_min
  }
Loading

2. Entities

road

A road the API can name, keyed by its official designation. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
road_ref key yes upper case, no space (A8, B27) CONV-011 Identity and designation road
road_class enum<road_class> yes motorway, federal, state, urban, other Class of the road road_class filter
name ltext no A descriptive name, for example the end points name
length_km decimal(6,1) no km > 0 Signed length toKm of the whole road
geometry line no WGS 84 Centre line, both directions corridor building
states list<key> yes ISO 3166-2 States the road crosses states[]

junction

A numbered or named point on a road: an exit, an interchange, a motorway triangle or a service area. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
junction_id id yes Identity nearestJunction.id (jn_…)
road_ref key → road yes The road it lies on nearestJunction.road
number text no as signed (61, 12a) Junction number nearestJunction.number
name text yes Junction name as signed nearestJunction.name, position.junctionFrom/junctionTo
junction_kind enum<junction_kind> yes exit, interchange, triangle, service_area, other What it is none in v1
chainage_km decimal(6,1) no km 0 … road.length_km Position along the road snapping of from/to
location point yes WGS 84 Position nearestJunction.distanceM

traffic_event

One situation as its source publishes it, in its current version. Retention: the current version is an event record; each version is also an observation in traffic_event_observation (OBS); an ended event stays readable for the grace period (TRN).

Field Type Req Unit / format Constraints and values Description API field
event_id id yes Identity id (rs_…)
event_kind enum<event_kind> yes see dictionary What it is kind
severity enum<severity> yes ordered info < minor < lane_closed < major < road_closed Effect on traffic, by a documented mapping from the published facts severity, lampReason
road_ref key → road no null off the held network Affected road road
road_class enum<road_class> yes Class of the affected road road_class filter
direction enum<direction> yes north, east, south, west, both, unknown Affected carriageway direction
direction_label text no Signed destination of the carriageway, as published directionText
from_km, to_km decimal(6,1) no km from_km ≤ to_km after orientation Chainage of the primary stretch position.fromKm, position.toKm
from_junction_id, to_junction_id id → junction no Junctions that bound the stretch position.junctionFrom, position.junctionTo
location point no WGS 84 null when the source gives no position and none can be derived Representative point location, distance ordering
shape geometry no WGS 84 Line or point geometry of the primary stretch geometry
valid_from instant yes UTC Start of validity, planned or observed validity.from
valid_to instant no UTC > valid_from; null = open-ended End of validity validity.until
lanes_closed int no ≥ 0 Lanes closed, where published lanes.closed
lanes_total int no ≥ lanes_closed Lanes in that direction, where published lanes.total
delay_min int no min ≥ 0 Published delay delayMin
affected_length_m int no m ≥ 0 Published length of the affected stretch lengthM
headline ltext yes plain text Short title headline
description ltext no plain text Longer text description
text_lang text yes BCP 47 Language of the original text textLanguage
primary_event_id id → traffic_event no not self Set when this record describes the same real-world situation as another source's record; the primary is served, the duplicates add their attribution (FR-ROAD-007) meta.attribution[]
envelope changed_at is the last content change updatedAt, sourceFamily

event_extent

Further stretches of one event that affects more than one place, for example roadworks with several lane closures. Position 0 is the primary stretch held on the event itself. Retention follows the event.

Field Type Req Unit / format Constraints and values Description API field
event_id id → traffic_event yes Owning event none
position int yes ≥ 1, unique per event Order of the stretch none
road_ref key → road no Road of this stretch corridor matching
from_km, to_km decimal(6,1) no km Chainage corridor matching
shape geometry no WGS 84 Geometry geometry (full)

traffic_event_observation

One version of an event as it was at observed_at. A new observation is added whenever the event's content changes; none is ever updated. Retention OBS.

Field Type Req Unit / format Constraints and values Description API field
event_id id → traffic_event yes The event history item id
observed_at instant yes UTC When this version was current observedAt
version_no int yes ≥ 1, increasing per event Version counter none
event_kind, severity, direction, from_km, to_km, valid_from, valid_to, lanes_closed, lanes_total, delay_min, affected_length_m, headline, description, text_lang, location as on traffic_event as there The event's fields as of this version history item fields

3. Keys and relationships

Relationship Cardinality Rule
road → junction one to many A junction lies on exactly one road; an interchange of two roads is one junction per road
traffic_event → road many to zero-or-one Null for events off the held network or without a road reference
traffic_event → junction (from, to) many to zero-or-one each Bounding junctions where known
traffic_event → event_extent one to many Extra stretches only
traffic_event → traffic_event_observation one to many At least one per event
traffic_event → primary traffic_event many to zero-or-one Duplicate folding across sources; a primary is never itself a duplicate

Natural key: origin_key within source_ref, the publisher's own situation identifier.

4. Temporal behaviour

  • Active at instant t: valid_from ≤ t and (valid_to is null or t < valid_to) and not withdrawn. "Active within the look-ahead" widens t to a window bounded by roads.max_lookahead_h.
  • Ended events (past valid_to, or withdrawn by their source) stay readable by id for roads.ended_retention_h (class TRN), then leave the read side.
  • History is read from traffic_event_observation only, inside a window bounded by history.max_window and the plan's history depth (class OBS, horizon configurable).

5. Access paths

Path Used by
By road_ref and direction, active events, ordered by chainage in the direction of travel motorway conditions, list motorways
Along a corridor: road_ref plus chainage range over the event and its extents; or a buffered route line tested against each event's box conditions along a section, route briefing
Ahead of a point: snap the point to the carriageway, then chainage greater (or smaller, by direction) up to within_km roadworks ahead
Within an area: spatial test on location or shape, by road_class conditions in an area
By key on event_id get a situation
By time window on traffic_event_observation.observed_at for one road condition history
Nearest junction to a point describe a point, section snapping

6. Licence and attribution

Each event names its source. When several sources describe one situation, the primary record is served once and meta.attribution[] carries every contributing source (FR-ROAD-007). Event texts are kept in the original language; translations are text_variant rows (Provenance).

7. Entity to API

Entity Operations Resource members
road GET /v1/motorways, path {road} everywhere motorway item, corridor
junction conditions, describe a point position.junctionFrom/To, nearestJunction, corridor.fromName/toName
traffic_event, event_extent conditions, roadworks ahead, conditions in an area, get a situation, route briefing, place overview road situation
traffic_event_observation GET /v1/motorways/{road}/conditions/history history item

The corridor lamp is not stored: it is a domain rule over the active events (FR-ROAD-004). Field-level mapping: Mapping.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally