Skip to content

Data Model Weather

mavrovde edited this page Nov 1, 2026 · 1 revision

Data Model: Weather

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, Weather Risk, Driving Rules and Composed Features section 1.

The domain holds official weather warnings and the warning areas they cover, and road weather observations from stations beside the road. Warnings are official texts: their levels are never re-graded and their original wording is always kept.

1. Diagram

erDiagram
  weather_warning ||--|{ warning_coverage : "covers"
  warning_area ||--o{ warning_coverage : "is covered by"
  admin_region |o--o{ warning_area : "matches"
  road_weather_station ||--o{ road_weather_observation : "reports"
  road |o--o{ road_weather_station : "is watched by"
  source ||--o{ weather_warning : "describes"
  source ||--o{ road_weather_station : "describes"
  weather_warning {
    string warning_id PK
    string hazard
    int warning_level
    string level_label
    string message_status
    string issuer_name
    string headline
    string description
    string instruction
    string text_lang
    instant valid_from
    instant valid_to
    instant published_at
    string source_ref FK
  }
  warning_area {
    string area_id PK
    string area_name
    string area_kind
    string region_code FK
    polygon boundary
  }
  warning_coverage {
    string warning_id FK
    string area_id FK
  }
  road_weather_station {
    string station_id PK
    string name
    string road_ref FK
    point location
    string source_ref FK
  }
  road_weather_observation {
    string station_id FK
    instant observed_at
    string surface_state
    decimal surface_temp_c
    decimal air_temp_c
    decimal dew_point_c
  }
Loading

2. Entities

weather_warning

One official warning in its current version. Retention: event record; each version is also kept as an observation (OBS); a warning that has expired or been cancelled leaves the read side after a configurable grace period (TRN).

Field Type Req Unit / format Constraints and values Description API field
warning_id id yes Identity id (ww_…)
hazard enum<hazard> yes see dictionary What the warning is about, mapped from the issuer's event code hazard, hazards filter
warning_level int yes 0 to 4; 0 is advance information The issuer's level, unchanged (FR-WEATHER-002) level, min_level filter
level_label ltext yes The issuer's name for the level levelName
message_status enum<message_status> yes issued, updated, cancelled Lifecycle of the message visibility (a cancelled warning is not active)
issuer_name text yes The issuing authority issuer
headline ltext yes official wording Headline headline
description ltext no official wording The official text, never edited description
instruction ltext no official wording The official advice instruction
text_lang text yes BCP 47 Language of the original wording originalLanguage
valid_from instant yes UTC Onset validity.from
valid_to instant no UTC null = until further notice Expiry validity.until
published_at instant no UTC When the issuer sent this version none in v1
envelope sourceFamily

Levels 1 to 4 are served; level 0 (advance information) is held but served only when an operation asks for it.

warning_area

An area the issuer warns for (a county, a municipality, a coastal strip, a lake), with its outline. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
area_id id yes Identity none
area_name text yes The issuer's name for the area area.name
area_kind enum<area_kind> yes county, municipality, coast, lake, sea, other Kind of area none in v1
region_code key → admin_region no The administrative region it matches, where one does place overview
boundary polygon yes WGS 84 valid polygon Outline area.geometry (with geometry=), intersection

warning_coverage

Which areas a warning covers. Link entity, no envelope.

Field Type Req Unit / format Constraints and values Description API field
warning_id id → weather_warning yes Warning none
area_id id → warning_area yes unique with warning_id Covered area area

road_weather_station

A measuring station beside a road. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
station_id id yes Identity none
name text no Name as published none in v1
road_ref key → road no Road it watches corridor matching
location point yes WGS 84 Position roadWeather[].location
envelope roadWeather[].sourceFamily

road_weather_observation

One measurement at a station. Retention OBS; never a forecast (FR-WEATHER-004).

Field Type Req Unit / format Constraints and values Description API field
station_id id → road_weather_station yes Station parent
observed_at instant yes UTC Measurement instant roadWeather[].observedAt
surface_state enum<surface_state> no dry, damp, wet, ice, snow, frost, unknown Road surface roadWeather[].surfaceState
surface_temp_c decimal(4,1) no °C Surface temperature roadWeather[].surfaceTempC
air_temp_c decimal(4,1) no °C Air temperature roadWeather[].airTempC
dew_point_c decimal(4,1) no °C Dew point none in v1

3. Keys and relationships

Relationship Cardinality Rule
weather_warning ↔ warning_area many to many through warning_coverage A warning covers at least one area
warning_area → admin_region many to zero-or-one
road_weather_station → road_weather_observation one to many
road_weather_station → road many to zero-or-one

A warning's natural key is the issuer's message identifier within its source; an update of the same warning is a new version of the same record.

4. Temporal behaviour

  • A warning is active at t when valid_from ≤ t < valid_to (or valid_to is null), it is not cancelled and not withdrawn. Look-ahead widens t to weather.max_lookahead_h.
  • Each new version is appended as an observation; the current version is replaced in place.
  • Road weather is OBS: the newest observation per station inside the family's freshness horizon is the current one.

5. Access paths

Path Used by
Areas whose boundary contains a point, then their active warnings weather risk, near
Areas whose boundary intersects a buffered corridor weather risk, along; route briefing
Stations along a corridor (by road_ref or buffered line), newest observation each roadWeather[]

6. Licence and attribution

Warnings are official texts: the issuer is carried, levels are unchanged, and the original wording stays available beside any translation (FR-WEATHER-003). Translations are text_variant rows marked with their origin (Provenance).

7. Entity to API

Entity Operations Resource members
weather_warning, warning_coverage, warning_area GET/POST /v1/weather-risk, route briefing and place overview weather part warnings[]
road_weather_station, road_weather_observation weather risk, along roadWeather[]

The lamp of a weather answer is a domain rule over the active warning levels, not stored. Field-level mapping: Mapping.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally