Skip to content

Data Model Parking

mavrovde edited this page Nov 1, 2026 · 1 revision

Data Model: Parking

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, Energy and Parking.

The domain holds parking facilities (garages, lots, park and ride, rest areas, lorry parking) with their capacity per vehicle class and their live occupancy, and sharing stations with their live count of available vehicles.

1. Diagram

erDiagram
  parking_facility ||--o{ facility_capacity : "offers"
  parking_facility ||--o{ occupancy_observation : "reports"
  road |o--o{ parking_facility : "serves"
  sharing_station ||--o{ sharing_availability_observation : "reports"
  source ||--o{ parking_facility : "describes"
  source ||--o{ occupancy_observation : "describes"
  source ||--o{ sharing_station : "describes"
  parking_facility {
    string facility_id PK
    string name
    string parking_kind
    string operator_name
    string road_ref FK
    string direction
    point location
    polygon outline
    bool acceptance_required
    string source_ref FK
  }
  facility_capacity {
    string facility_id FK
    string vehicle_class
    int total_spaces
  }
  occupancy_observation {
    string facility_id FK
    instant observed_at
    int free_spaces
    int total_spaces
    string occupancy_status
    string source_ref FK
  }
  sharing_station {
    string station_id PK
    string name
    string operator_name
    string vehicle_class
    point location
    string source_ref FK
  }
  sharing_availability_observation {
    string station_id FK
    instant observed_at
    int available_vehicles
  }
Loading

2. Entities

parking_facility

A place to park. Withdrawn facilities are soft-closed and kept: "this rest area no longer exists" is an answer. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
facility_id id yes Identity id (pk_…)
name text no Name as published name
parking_kind enum<parking_kind> yes garage, lot, park_and_ride, rest_area, truck_parking, on_street, other What it is kind, kind filter
operator_name text no Operator as published none in v1
road_ref key → road no The motorway it serves, for rest areas and lorry parking corridor matching
direction enum<direction> no Carriageway it is reached from corridor matching
location point yes WGS 84 Position of the entrance or centre location, distanceM, distanceAlongKm, detourM
outline polygon no WGS 84 Area, where published geometry (full)
acceptance_required bool yes True when the occupancy of this facility is served only after the key holder accepted the source's terms (SEC-030) termsRequired
envelope sourceFamily

facility_capacity

Spaces per vehicle class, as published. A facility without published capacity has no rows. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
facility_id id → parking_facility yes The facility none
vehicle_class enum<vehicle_class> yes car, lorry, coach, motorhome, disabled, all Who the spaces are for vehicleClasses[], capacity.byVehicle, vehicle filter
total_spaces int yes ≥ 0 Number of spaces capacity.total (row all), capacity.byVehicle

occupancy_observation

One live reading of a facility. Retention OBS; the current occupancy is the newest reading inside the family's freshness horizon, otherwise none (occupancy: null, FR-PARK-002).

Field Type Req Unit / format Constraints and values Description API field
facility_id id → parking_facility yes The facility parent item
observed_at instant yes UTC When the reading was true per the source occupancy.observedAt
free_spaces int no ≥ 0 Free spaces, where published occupancy.free, free_min filter, sort=free
total_spaces int no ≥ free_spaces Spaces counted in this reading, which may differ from the static capacity none
occupancy_status enum<occupancy_status> yes free, filling, full, closed, unknown Published or mapped status occupancy.state
source_ref key → source yes Source of the reading; may differ from the facility's sourceFamily

occupancy.trend is not stored: it is a domain rule over the readings of a configured recent window (rising, falling, steady, unknown).

sharing_station

A fixed station of a vehicle-sharing scheme. Retention REF.

Field Type Req Unit / format Constraints and values Description API field
station_id id yes Identity id (sh_…)
name text no Name as published name
operator_name text no Scheme operator operator
vehicle_class enum<vehicle_class> yes car in v1 Vehicles offered vehicle filter
location point yes WGS 84 Position location, distanceM
envelope sourceFamily

sharing_availability_observation

One live count of vehicles at a station. Retention OBS.

Field Type Req Unit / format Constraints and values Description API field
station_id id → sharing_station yes The station parent item
observed_at instant yes UTC When the count was true vehiclesAvailable.observedAt
available_vehicles int no ≥ 0 Vehicles available vehiclesAvailable

3. Keys and relationships

Relationship Cardinality Rule
parking_facility → facility_capacity one to many One row per vehicle class at most
parking_facility → occupancy_observation one to many Most facilities have none: no live reading is published
parking_facility → road many to zero-or-one Only for facilities on a motorway
sharing_station → sharing_availability_observation one to many

A facility's natural key is unique only within its source; the same rest area described by two sources is two records unless a documented matching rule links them. Each record keeps its own licence (DM-011).

4. Temporal behaviour

  • Facilities and stations: REF, soft-closed when withdrawn.
  • Occupancy and availability: OBS, append-only, horizon configurable. A reading older than the family's stale threshold is reported with stale freshness.
  • Occupancy is never inferred from capacity (FR-PARK-002, ENV-041).

5. Access paths

Path Used by
Nearest facilities within a radius, filtered by vehicle_class and parking_kind, with the newest reading parking options, near
Along a corridor: road_ref and direction for motorway facilities, plus a buffered line for the rest parking options, along; route briefing
Nearest stations within a radius, with the newest count sharing options

6. Licence and attribution

Parking data reaches the read side under several licences, so the licence is a property of each record, not of the domain. Share-alike facilities and their readings stay in records of their own source and carry the share-alike flag and offer. Facilities whose source requires the key holder's acceptance of terms have acceptance_required set; their occupancy is withheld until acceptance (FR-PARK-003).

7. Entity to API

Entity Operations Resource members
parking_facility, facility_capacity GET/POST /v1/parking-options, route briefing parking part parking item, capacity
occupancy_observation parking options occupancy
sharing_station, sharing_availability_observation GET /v1/sharing-options sharing item

Field-level mapping: Mapping.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally