Skip to content

Spec Resource Model

mavrovde edited this page Nov 1, 2026 · 2 revisions

Spec: Resource Model

Part of the Technical Specification. Requirement prefixes: FR-LOC (shared inputs) and FR-GEN (rules for every operation). The model follows the bounded contexts of the Domain Model: domains and features, never storage. No table, view or column of any store appears in a path, a parameter or a payload. The logical entities each operation composes, and the trace from every public field to them, are on Data Model and Data Model: Mapping.

1. Operation catalogue (v1)

Domain Operation Method and path Scope Cache family Specified on
Places Search places GET /v1/places places places [[Places
Places Get a place GET /v1/places/{placeId} places places [[Places
Places Describe a point GET /v1/locations/describe places places [[Places
Places Search addresses GET /v1/addresses places places [[Places
Places Points of interest GET /v1/points-of-interest places places [[Places
Roads List motorways GET /v1/motorways roads roads [[Roads
Roads Motorway conditions GET /v1/motorways/{road}/conditions roads roads [[Roads
Roads Roadworks ahead GET /v1/motorways/{road}/roadworks-ahead roads roads [[Roads
Roads Conditions in an area GET /v1/road-conditions roads roads [[Roads
Roads Get a situation GET /v1/road-situations/{situationId} roads roads [[Roads
Roads Condition history GET /v1/motorways/{road}/conditions/history roads + history none (immutable window) [[Roads
Energy Refuel options GET/POST /v1/refuel-options energy fuel [[Energy and Parking
Energy Charging options GET/POST /v1/charging-options energy charging [[Energy and Parking
Parking Parking options GET/POST /v1/parking-options parking parking [[Energy and Parking
Parking Sharing options GET /v1/sharing-options parking parking [[Energy and Parking
Public transport Search stop places GET /v1/stop-places transit places [[Transit and Accessibility
Public transport Departures GET /v1/stop-places/{stopPlaceId}/departures transit departures [[Transit and Accessibility
Public transport Disruptions at a stop GET /v1/stop-places/{stopPlaceId}/disruptions transit departures [[Transit and Accessibility
Public transport Disruptions in an area GET /v1/disruptions transit departures [[Transit and Accessibility
Accessibility Station accessibility GET /v1/stop-places/{stopPlaceId}/accessibility accessibility accessibility [[Transit and Accessibility
Weather risk Weather risk GET/POST /v1/weather-risk weather weather [[Weather, Rules and Composed
Driving rules Rule topic GET /v1/driving-rules rules rules [[Weather, Rules and Composed
Composed Route briefing GET/POST /v1/route-briefing per part minimum of parts [[Weather, Rules and Composed
Composed Place overview GET /v1/places/{placeId}/overview per part minimum of parts [[Weather, Rules and Composed
Service Sources, meta, health, description /v1/sources, /v1/meta, /healthz, /readyz, /v1/openapi.json, /docs public [[Service Endpoints

GET /v1/places/{placeId} and GET /v1/road-situations/{situationId} extend the plan on API Design so that every id the API returns can be resolved again.

2. Shared location inputs

flowchart LR
  I[Location input] --> A{Which form?}
  A -->|at = lat,lon| P[Point]
  A -->|place = id| R[Resolve place]
  A -->|q = text| G[Gazetteer search]
  G -->|one clear match| R
  G -->|several| X[422 ambiguous-place<br/>with candidates]
  G -->|none| N[404 not-found]
  R --> P
  P --> D{Inside coverage?}
  D -->|no| O[422 outside-coverage]
  D -->|yes| Area[Area: point and radius, box, or corridor]
Loading
Parameter Type and format Default Bounds Meaning
at lat,lon, decimal degrees lat −90..90, lon −180..180, ≤ 6 decimals A point
place place id A place from the place search
q string, 1–120 characters A free-text place
radius_m integer per operation (geo.default_radius_m, design 5 000) 1 – geo.max_radius_m (design 50 000) Search radius around the point
bbox min_lon,min_lat,max_lon,max_lat area ≤ geo.max_bbox_km2 A box instead of a radius
road, direction road reference, enum north, east, south, west, both both A motorway and direction
from, to location (place id, lat,lon, or text) Section start and end on road, projected to the road
from_km, to_km number, one decimal 0 – road length Section by chainage instead of from/to
route encoded polyline (precision 5) ≤ geo.max_route_points points, length ≤ geo.max_route_km A client route
buffer_m integer geo.route_buffer_m (design 2 000) 100 – 10 000 Corridor half-width around a route
ID Requirement Verification
FR-LOC-001 An operation that needs a location MUST accept exactly one of at, place or q. Zero or several of them is 400 (invalid-parameter). Handler
FR-LOC-002 A q text MUST be resolved by the gazetteer. A single clear match MUST be used and reported in meta.query; several plausible matches MUST yield 422 (ambiguous-place) with at most places.max_candidates candidates (id, name, kind, region, location); no match MUST yield 404 (not-found). Handler
FR-LOC-003 A point outside the coverage area (Germany plus a border margin of geo.coverage_margin_m) MUST yield 422 (outside-coverage). Unit
FR-LOC-004 "Along" operations MUST accept either a motorway section (road with direction and from/to or from_km/to_km) or a client route with buffer_m; supplying both forms is 400. Handler
FR-LOC-005 A route MUST be decoded with the standard polyline algorithm at precision 5 (latitude first) and MUST be refused with 400 when malformed, 422 (area-too-large) when it exceeds the point or length limit. Long routes SHOULD be sent with a query POST (PROT-012). Unit
FR-LOC-006 Every area (radius, box, corridor) MUST be bounded by configuration; exceeding a bound is 422 (area-too-large) naming the limit. Config
FR-LOC-007 The API MUST NOT compute routes. A route between places is the client's input; from/to only delimit a section of a named road. Review

3. Shared value types

Type JSON shape Notes
GeoPoint {"lat": n, "lon": n} WGS 84, six decimals
Money {"amount": "1.789", "currency": "EUR"} CONV-007
TimeWindow {"from", "fromLocal", "until", "untilLocal"} until null when open-ended
Lamp enum green, amber, red, unknown A summary computed by a documented, tested domain rule, identical to the MCP server's
AdminRegion {"state": "DE-BY", "stateName", "district", "municipality"} Names in the response language where available
Address {"street", "houseNumber", "postcode", "locality", "state"} Members null when not known
OpeningState enum open, closed, unknown Never a nullable boolean (CONV-012)
Observed<T> {…, "observedAt", "observedAtLocal"} Any live state carries when it was observed

4. Rules for every operation

ID Requirement Verification
FR-GEN-001 Each operation MUST declare in the OpenAPI document its scope, its source families, its cache family, its MCP counterpart where one exists, its default and maximum page size, its order, and at least one executed example. Lint
FR-GEN-002 For the same input and the same data, an operation with an MCP counterpart MUST answer the same facts (ids, names, positions to five decimals, prices, states, instants, families, note texts). Parity
FR-GEN-003 No path segment, parameter name or payload member MUST equal a storage name, except a short reviewed allow-list of generic words (id, name). Lint
FR-GEN-004 Live states (availability, occupancy, prices, facility states, expected times) MUST carry their own observation instant. Contract
FR-GEN-005 Text fields from publishers (headlines, descriptions) MUST be returned as plain text, never HTML, with control characters removed; the language of each such text MUST be tagged when it differs from meta.language. Unit
FR-GEN-006 An operation that is switched off by configuration (endpoints.disabled) MUST answer 404 (feature-disabled) and MUST disappear from the served OpenAPI document. Config

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally