Repository navigation
Spec Common Envelope
Part of the Technical Specification. Requirement prefix: ENV. This page refines the response shape on API Design.
Every successful JSON data response is one object with three members:
{
"data": { },
"meta": { },
"links": { }
}-
dataholds the answer: an object for a single resource or a composed answer, an array for a list. -
metaholds provenance, freshness, paging, language and warnings. -
linksholds absolute URLs related to this response.
| Member | Type | Presence | Meaning |
|---|---|---|---|
requestId |
string | always | The request id, equal to the X-Request-Id header |
generatedAt |
instant | always | When the service produced this body |
asOf |
instant or null | data responses | The oldest dataAsOf among the families that contributed: a conservative "this is at least this fresh" |
language |
BCP 47 tag | always | The language of the texts in data
|
freshness[] |
array | data responses | One entry per contributing source family, see 1.2 |
attribution[] |
array | data responses | One entry per contributing source family, see [[Spec: Data Licensing and Attribution |
notes |
object | data responses |
condition[] and purpose[], the verbatim licence notes, see the same page |
parts[] |
array | composed features | One entry per part: part, status (ok, timeout, not_permitted, unavailable, not_requested), optional problemType
|
page |
object | list operations |
limit, hasMore, and nextCursor when hasMore is true |
warnings[] |
array | when any |
{code, detail}; codes: served_stale, data_stale, partial, truncated_geometry, language_fallback, deprecated
|
query |
object | always on data responses | The normalised, resolved input actually answered (for example the resolved place for a q= text) |
{
"family": "roads.federal",
"dataAsOf": "2026-11-01T13:04:30Z",
"ageS": 30,
"staleAfterS": 900,
"stale": false
}ageS is generatedAt − dataAsOf in whole seconds. stale is true when ageS > staleAfterS, the configured design threshold for the family (freshness.stale_after.<family>, see Spec: Non-Functional Requirements NFR-FRESH).
self (always), next (when there is a further page), sources (the source register), docs (the operation's reference page).
GET /v1/charging-options?at=48.137,11.575&radius_m=2000&min_kw=50&limit=1
{
"data": [
{
"id": "cs_3Fq9kT",
"name": "Example charging site",
"operator": "Example Energy GmbH",
"location": {"lat": 48.139821, "lon": 11.566102},
"distanceM": 780,
"access": "public",
"summary": {"chargePoints": 4, "availableNow": 2, "maxPowerKw": 150},
"chargePoints": [
{
"id": "cs_3Fq9kT.1",
"connectors": [{"type": "ccs2", "maxPowerKw": 150}],
"availability": {
"state": "available",
"observedAt": "2026-11-01T13:03:10Z",
"observedAtLocal": "2026-11-01T14:03:10+01:00"
}
}
],
"sourceFamily": "charging.availability"
}
],
"meta": {
"requestId": "0192e3b4-7c1a-7d2e-9a10-5b6c7d8e9f01",
"generatedAt": "2026-11-01T13:05:00Z",
"asOf": "2026-11-01T13:03:10Z",
"language": "en",
"freshness": [
{"family": "charging.availability", "dataAsOf": "2026-11-01T13:03:10Z", "ageS": 110, "staleAfterS": 1800, "stale": false}
],
"attribution": [
{
"family": "charging.availability",
"publisher": "Example publisher",
"text": "Data: Example publisher, licence CC BY 4.0",
"licence": "Creative Commons Attribution 4.0 International",
"licenceId": "CC-BY-4.0",
"licenceUrl": "https://creativecommons.org/licenses/by/4.0/",
"shareAlike": false,
"changesMade": "Selected, filtered by distance and re-formatted."
}
],
"notes": {"condition": [], "purpose": []},
"page": {"limit": 1, "hasMore": true, "nextCursor": "eyJ2IjoxLCJwIjoi…"},
"warnings": [],
"query": {"at": {"lat": 48.137, "lon": 11.575}, "radiusM": 2000, "minKw": 50}
},
"links": {
"self": "https://api.viafrei.de/v1/charging-options?at=48.137,11.575&radius_m=2000&min_kw=50&limit=1",
"next": "https://api.viafrei.de/v1/charging-options?at=48.137,11.575&radius_m=2000&min_kw=50&limit=1&cursor=eyJ2IjoxLCJwIjoi…",
"sources": "https://api.viafrei.de/v1/sources",
"docs": "https://api.viafrei.de/docs#operation/listChargingOptions"
}
}All values are placeholders, not data.
| ID | Requirement | Verification |
|---|---|---|
| ENV-001 | Every successful JSON data response MUST have exactly the top-level members data, meta and links. |
Contract |
| ENV-002 |
meta.requestId, meta.generatedAt and meta.language MUST be present on every successful response. |
Contract |
| ENV-003 | Every data response MUST carry non-empty meta.attribution and meta.freshness with one entry per contributing family, and every item in data that comes from one family MUST name it in sourceFamily. An empty result MUST still carry the attribution of the families that were consulted. |
Contract |
| ENV-004 |
meta.asOf MUST equal the minimum dataAsOf of meta.freshness. |
Unit |
| ENV-005 |
meta.query MUST report the resolved input, so that a client can see which place a free-text query was resolved to. |
Handler |
| ENV-006 | Warnings MUST use only the documented codes; a new code is an additive change and clients MUST tolerate unknown codes. | Contract |
With Accept: application/geo+json (or format=geojson), a list operation answers an RFC 7946 FeatureCollection. Each item becomes a Feature whose id is the item id, whose geometry is its location or shape, and whose properties are the item without its location fields. meta and links are carried as foreign members of the collection.
| ID | Requirement | Verification |
|---|---|---|
| ENV-010 | The GeoJSON variant MUST carry the same meta (including attribution and notes) as the JSON variant. |
Contract |
| ENV-011 | Positions MUST be [lon, lat], rounded to six decimals; no crs member MUST be emitted; a bbox member MAY be emitted. |
Contract |
| ENV-012 | `geometry=none | point |
| ENV-013 | An operation whose answer is not a list of located items (for example meta, sources, driving-rules) MUST answer 406 to a GeoJSON-only Accept. |
Handler |
| ID | Requirement | Verification |
|---|---|---|
| ENV-020 | Lists MUST use keyset (cursor) pagination: limit and cursor parameters. Offset or page-number paging MUST NOT be offered. |
Contract |
| ENV-021 |
limit MUST default to pagination.default_limit (design default 50) and MUST be between 1 and the smaller of pagination.max_limit (design default 500) and the plan's maximum. A value outside is 400 (invalid-parameter), not silently clamped. |
Config |
| ENV-022 | Every list operation MUST define a total, stable order ending in the item id as the final tie-breaker, documented in the reference (for example "distance ascending, then id"). Paging through MUST neither repeat nor skip an item that did not change between requests. | Unit |
| ENV-023 | The cursor MUST be opaque, URL-safe, signed (configuration pagination.cursor_key), bound to the operation, the normalised filters, the key's permitted families and, for history, the time window, and MUST expire after pagination.cursor_ttl. A tampered, foreign or expired cursor is 400 (invalid-cursor). |
Security |
| ENV-024 | When a cursor is given, the other filters MUST be repeated unchanged or omitted; differing filters are 400 (invalid-cursor). |
Handler |
| ENV-025 | Live (non-history) lists MAY change between pages; the order is evaluated per page and items that moved MAY appear on a later page. History lists MUST be stable because their window is in the past or bounded. | Docs |
| ENV-026 | Totals (count) MUST NOT be returned for unbounded lists, because counting costs a full scan; hasMore replaces them. |
Review |
| ID | Requirement | Verification |
|---|---|---|
| ENV-030 | Filtering MUST be possible only through the parameters each operation declares. Generic filter languages (arbitrary field predicates, query expressions) MUST NOT be offered ([[Vision and Goals | Vision-and-Goals]]). |
| ENV-031 |
sort MUST accept only the values the operation declares (for example distance, price); a leading - for descending MAY be declared per value. Every declared sort ends in the id tie-breaker. |
Contract |
| ENV-032 |
fields MUST select a sparse field set of data items by comma-separated dot paths (fields=id,name,offers.price). Unknown paths are 400. id and sourceFamily MUST always be included. meta and links MUST NOT be reducible, so attribution can never be dropped. |
Handler |
| ENV-033 |
fields MUST NOT change the entity tag semantics: it is part of the normalised query. |
Unit |
| ID | Requirement | Verification |
|---|---|---|
| ENV-040 |
Absent means not applicable to this item or not selected by fields. null means applicable but unknown or not published by the source. Empty array means known to be none. The schema of every field MUST state whether it is nullable and whether it is always present. |
Contract |
| ENV-041 | The service MUST NOT invent values to fill gaps: an unpublished occupancy is null, never 0. |
Mapping |
| ENV-042 | Numbers MUST NOT be sent as strings, except monetary amounts (CONV-007). | Contract |
| ID | Requirement | Verification |
|---|---|---|
| ENV-050 | Every enumeration in the public schema is open: clients MUST tolerate values they do not know, and SHOULD treat them as other. The OpenAPI document MUST mark this with the extension x-extensible-enum: true and list the known values. |
Contract |
| ENV-051 | A storage code the service cannot map MUST be answered as other and counted in a metric; a raw storage string MUST never reach a payload ([[Domain Model |
Domain-Model]]). |
| ENV-052 | Clients MUST ignore unknown members in any object. New members MAY appear in v1 without notice. | Docs |
| ID | Requirement | Verification |
|---|---|---|
| ENV-060 | A deprecated operation or parameter MUST answer with Deprecation (RFC 9745, the date it was deprecated as an @<epoch> structured date), Sunset (RFC 8594, an HTTP date at least deprecation.min_notice later) and Link: <docs>; rel="deprecation", plus meta.warnings[] code deprecated. |
Handler |
| ENV-061 | A deprecated member of a payload MUST be marked deprecated: true in the OpenAPI document and keep its meaning until removal in the next major version. |
Contract |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference