Repository navigation
Spec OpenAPI Skeleton
Part of the Technical Specification.
Illustrative, normative in shape. The excerpt below fixes the shape of the common components (names, members, types, formats, required members) that the generated OpenAPI 3.1 document MUST have. Exact descriptions, examples and further operations are produced from the code (VER-006). Where this excerpt and a requirement on another spec page differ, the requirement governs.
openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
title: ViaFrei API
version: 1.0.0
summary: Keyed, read-only access to live German mobility context.
license:
name: Terms of use
url: https://viafrei.de/
x-ratelimit-headers-draft: draft-ietf-httpapi-ratelimit-headers
servers:
- url: https://api.viafrei.de/v1
security:
- bearerKey: []
- headerKey: []
tags:
- name: places
- name: roads
- name: energy
- name: parking
- name: transit
- name: accessibility
- name: weather
- name: rules
- name: composed
- name: service
paths:
/charging-options:
get:
operationId: listChargingOptions
summary: Charging sites near a point or along a corridor
tags: [energy]
x-scope: energy
x-source-families: [charging.register, charging.availability]
x-cache-family: charging
x-stability: stable
x-mcp-counterpart: charging station search
parameters:
- $ref: '#/components/parameters/At'
- $ref: '#/components/parameters/Place'
- $ref: '#/components/parameters/Q'
- $ref: '#/components/parameters/RadiusM'
- name: min_kw
in: query
schema: {type: number, minimum: 0, maximum: 1000, default: 0}
- name: connector
in: query
style: form
explode: false
schema:
type: array
items: {type: string, x-extensible-enum: true, enum: [type2, ccs2, chademo, type1, ccs1, schuko, nacs, other]}
- name: available_now
in: query
schema: {type: boolean, default: false}
- name: sort
in: query
schema: {type: string, enum: [distance, power], default: distance}
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Fields'
- $ref: '#/components/parameters/Geometry'
- $ref: '#/components/parameters/Lang'
- $ref: '#/components/parameters/IfNoneMatch'
responses:
'200':
description: Charging sites, nearest first.
headers:
ETag: {$ref: '#/components/headers/ETag'}
Cache-Control: {$ref: '#/components/headers/CacheControl'}
RateLimit: {$ref: '#/components/headers/RateLimit'}
RateLimit-Policy: {$ref: '#/components/headers/RateLimitPolicy'}
X-Request-Id: {$ref: '#/components/headers/RequestId'}
Link: {$ref: '#/components/headers/Link'}
content:
application/json:
schema:
type: object
required: [data, meta, links]
properties:
data:
type: array
items: {$ref: '#/components/schemas/ChargingSite'}
meta: {$ref: '#/components/schemas/Meta'}
links: {$ref: '#/components/schemas/Links'}
application/geo+json:
schema: {$ref: '#/components/schemas/FeatureCollection'}
'304': {$ref: '#/components/responses/NotModified'}
'400': {$ref: '#/components/responses/Problem'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Problem'}
'404': {$ref: '#/components/responses/Problem'}
'406': {$ref: '#/components/responses/Problem'}
'422': {$ref: '#/components/responses/Problem'}
'429': {$ref: '#/components/responses/TooManyRequests'}
'500': {$ref: '#/components/responses/Problem'}
'503': {$ref: '#/components/responses/Unavailable'}
/motorways/{road}/conditions:
get:
operationId: getMotorwayConditions
summary: Conditions on a motorway or a section of it
tags: [roads]
x-scope: roads
x-cache-family: roads
x-stability: stable
x-mcp-counterpart: road status
parameters:
- name: road
in: path
required: true
schema: {type: string, pattern: '^[AaBb] ?[0-9]{1,3}$', examples: [A8]}
- name: direction
in: query
schema: {type: string, enum: [north, east, south, west, both], default: both}
- name: from
in: query
schema: {type: string, maxLength: 120}
- name: to
in: query
schema: {type: string, maxLength: 120}
- name: from_km
in: query
schema: {type: number, minimum: 0, multipleOf: 0.1}
- name: to_km
in: query
schema: {type: number, minimum: 0, multipleOf: 0.1}
- name: kinds
in: query
style: form
explode: false
schema:
type: array
items: {$ref: '#/components/schemas/SituationKind'}
- name: min_severity
in: query
schema: {$ref: '#/components/schemas/Severity'}
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Geometry'
- $ref: '#/components/parameters/Lang'
responses:
'200':
description: The corridor, its lamp and its situations.
content:
application/json:
schema:
type: object
required: [data, meta, links]
properties:
data:
type: object
required: [corridor, lamp, situations]
properties:
corridor: {$ref: '#/components/schemas/Corridor'}
lamp: {$ref: '#/components/schemas/Lamp'}
lampReason: {type: string}
situations:
type: array
items: {$ref: '#/components/schemas/RoadSituation'}
meta: {$ref: '#/components/schemas/Meta'}
links: {$ref: '#/components/schemas/Links'}
'304': {$ref: '#/components/responses/NotModified'}
'400': {$ref: '#/components/responses/Problem'}
'401': {$ref: '#/components/responses/Unauthorized'}
'403': {$ref: '#/components/responses/Problem'}
'404': {$ref: '#/components/responses/Problem'}
'422': {$ref: '#/components/responses/Problem'}
'429': {$ref: '#/components/responses/TooManyRequests'}
'503': {$ref: '#/components/responses/Unavailable'}
components:
securitySchemes:
bearerKey:
type: http
scheme: bearer
bearerFormat: vf_live_<keyId>_<secret><checksum>
description: API key as an RFC 6750 bearer token. Never in the URL.
headerKey:
type: apiKey
in: header
name: X-API-Key
parameters:
At:
name: at
in: query
description: A point as lat,lon in WGS 84 decimal degrees.
schema: {type: string, pattern: '^-?[0-9]{1,2}(\.[0-9]{1,6})?,-?[0-9]{1,3}(\.[0-9]{1,6})?$'}
Place:
name: place
in: query
schema: {type: string, pattern: '^pl_[A-Za-z0-9]{1,32}$'}
Q:
name: q
in: query
schema: {type: string, minLength: 1, maxLength: 120}
RadiusM:
name: radius_m
in: query
schema: {type: integer, minimum: 1, maximum: 50000, default: 5000}
Limit:
name: limit
in: query
schema: {type: integer, minimum: 1, maximum: 500, default: 50}
Cursor:
name: cursor
in: query
schema: {type: string, maxLength: 512, pattern: '^[A-Za-z0-9_-]+$'}
Fields:
name: fields
in: query
style: form
explode: false
schema: {type: array, items: {type: string, pattern: '^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*$'}}
Geometry:
name: geometry
in: query
schema: {type: string, enum: [none, point, simplified, full], default: point}
Lang:
name: lang
in: query
description: BCP 47 language tag. Overrides Accept-Language. Default de.
schema: {type: string, maxLength: 35, examples: [de, en]}
IfNoneMatch:
name: If-None-Match
in: header
schema: {type: string}
headers:
ETag:
schema: {type: string, examples: ['W/"3f9a1c"']}
CacheControl:
schema: {type: string, examples: ['private, max-age=60']}
RateLimit:
description: Remaining units per policy, IETF RateLimit fields, RFC 9651 syntax.
schema: {type: string, examples: ['"burst";r=17;t=1, "day";r=8412;t=38211']}
RateLimitPolicy:
schema: {type: string, examples: ['"burst";q=20;w=1, "day";q=10000;w=86400']}
RetryAfter:
schema: {type: integer, minimum: 0}
RequestId:
schema: {type: string, format: uuid}
Link:
schema: {type: string}
responses:
NotModified:
description: The representation has not changed.
headers:
ETag: {$ref: '#/components/headers/ETag'}
X-Request-Id: {$ref: '#/components/headers/RequestId'}
Problem:
description: A problem.
content:
application/problem+json:
schema: {$ref: '#/components/schemas/Problem'}
Unauthorized:
description: Missing or invalid key.
headers:
WWW-Authenticate:
schema: {type: string, examples: ['Bearer realm="viafrei-api", error="invalid_token"']}
content:
application/problem+json:
schema: {$ref: '#/components/schemas/Problem'}
TooManyRequests:
description: Rate limited, quota exceeded or overloaded.
headers:
Retry-After: {$ref: '#/components/headers/RetryAfter'}
content:
application/problem+json:
schema: {$ref: '#/components/schemas/Problem'}
Unavailable:
description: Deadline exhausted or storage unavailable.
headers:
Retry-After: {$ref: '#/components/headers/RetryAfter'}
content:
application/problem+json:
schema: {$ref: '#/components/schemas/Problem'}
schemas:
Problem:
type: object
required: [type, title, status, detail, instance, requestId, retryable]
properties:
type: {type: string, format: uri, examples: ['https://api.viafrei.de/problems/invalid-parameter']}
title: {type: string}
status: {type: integer, minimum: 400, maximum: 599}
detail: {type: string}
instance: {type: string, format: uri-reference}
requestId: {type: string, format: uuid}
retryable: {type: boolean}
retryAfter: {type: integer, minimum: 0}
errors:
type: array
items:
type: object
required: [code, detail]
properties:
parameter: {type: string}
pointer: {type: [string, 'null'], format: json-pointer}
code: {type: string}
detail: {type: string}
candidates:
type: array
items: {$ref: '#/components/schemas/PlaceRef'}
Attribution:
type: object
required: [family, publisher, text, licence, licenceUrl, shareAlike]
properties:
family: {type: string, pattern: '^[a-z]+(\.[a-z_]+)+$'}
publisher: {type: string}
text: {type: string, description: The exact notice the licence requires.}
licence: {type: string}
licenceId: {type: [string, 'null']}
licenceUrl: {type: string, format: uri}
shareAlike: {type: boolean}
shareAlikeOffer: {type: [string, 'null'], format: uri}
changesMade: {type: [string, 'null']}
termsUrl: {type: [string, 'null'], format: uri}
Note:
type: object
required: [family, text, lang]
properties:
family: {type: string}
text: {type: string, description: Verbatim. Never translated in place.}
lang: {type: string}
Freshness:
type: object
required: [family, dataAsOf, ageS, staleAfterS, stale]
properties:
family: {type: string}
dataAsOf: {type: string, format: date-time}
ageS: {type: integer, minimum: 0}
staleAfterS: {type: integer, minimum: 0}
stale: {type: boolean}
Page:
type: object
required: [limit, hasMore]
properties:
limit: {type: integer, minimum: 1}
hasMore: {type: boolean}
nextCursor: {type: string}
Meta:
type: object
required: [requestId, generatedAt, language]
properties:
requestId: {type: string, format: uuid}
generatedAt: {type: string, format: date-time}
asOf: {type: [string, 'null'], format: date-time}
language: {type: string}
freshness: {type: array, items: {$ref: '#/components/schemas/Freshness'}}
attribution: {type: array, minItems: 1, items: {$ref: '#/components/schemas/Attribution'}}
notes:
type: object
required: [condition, purpose]
properties:
condition: {type: array, items: {$ref: '#/components/schemas/Note'}}
purpose: {type: array, items: {$ref: '#/components/schemas/Note'}}
parts:
type: array
items:
type: object
required: [part, status]
properties:
part: {type: string}
status: {type: string, x-extensible-enum: true, enum: [ok, timeout, not_permitted, unavailable, not_requested]}
problemType: {type: string, format: uri}
page: {$ref: '#/components/schemas/Page'}
warnings:
type: array
items:
type: object
required: [code]
properties:
code: {type: string, x-extensible-enum: true, enum: [served_stale, data_stale, partial, truncated_geometry, language_fallback, deprecated, key_expiring]}
detail: {type: string}
query: {type: object}
Links:
type: object
required: [self]
properties:
self: {type: string, format: uri}
next: {type: string, format: uri}
sources: {type: string, format: uri}
docs: {type: string, format: uri}
GeoPoint:
type: object
required: [lat, lon]
properties:
lat: {type: number, minimum: -90, maximum: 90}
lon: {type: number, minimum: -180, maximum: 180}
Money:
type: object
required: [amount, currency]
properties:
amount: {type: string, pattern: '^-?[0-9]+(\.[0-9]{1,4})?$'}
currency: {type: string, pattern: '^[A-Z]{3}$', examples: [EUR]}
Lamp: {type: string, x-extensible-enum: true, enum: [green, amber, red, unknown]}
Severity: {type: string, x-extensible-enum: true, enum: [info, minor, lane_closed, major, road_closed]}
SituationKind: {type: string, x-extensible-enum: true, enum: [closure, roadworks, jam, accident, hazard, restriction, weather, other]}
TimeWindow:
type: object
required: [from, fromLocal, until, untilLocal]
properties:
from: {type: string, format: date-time}
fromLocal: {type: string, format: date-time}
until: {type: [string, 'null'], format: date-time}
untilLocal: {type: [string, 'null'], format: date-time}
PlaceRef:
type: object
required: [id, name, kind]
properties:
id: {type: string}
name: {type: string}
kind: {type: string}
location: {$ref: '#/components/schemas/GeoPoint'}
Corridor:
type: object
required: [road, direction]
properties:
road: {type: string}
direction: {type: string}
fromKm: {type: number}
toKm: {type: number}
fromName: {type: [string, 'null']}
toName: {type: [string, 'null']}
RoadSituation:
type: object
required: [id, kind, severity, validity, updatedAt, sourceFamily]
properties:
id: {type: string, pattern: '^rs_'}
kind: {$ref: '#/components/schemas/SituationKind'}
severity: {$ref: '#/components/schemas/Severity'}
road: {type: [string, 'null']}
direction: {type: string}
validity: {$ref: '#/components/schemas/TimeWindow'}
delayMin: {type: [integer, 'null'], minimum: 0}
lengthM: {type: [integer, 'null'], minimum: 0}
headline: {type: string}
updatedAt: {type: string, format: date-time}
sourceFamily: {type: string}
ChargingSite:
type: object
required: [id, name, location, summary, chargePoints, sourceFamily]
properties:
id: {type: string, pattern: '^cs_'}
name: {type: string}
operator: {type: [string, 'null']}
location: {$ref: '#/components/schemas/GeoPoint'}
distanceM: {type: integer, minimum: 0}
access: {type: string, x-extensible-enum: true, enum: [public, restricted]}
summary:
type: object
required: [chargePoints, availableNow, maxPowerKw]
properties:
chargePoints: {type: integer, minimum: 0}
availableNow: {type: [integer, 'null'], minimum: 0}
maxPowerKw: {type: [number, 'null'], minimum: 0}
chargePoints: {type: array, items: {type: object}}
sourceFamily: {type: string}
FeatureCollection:
type: object
required: [type, features, meta]
properties:
type: {const: FeatureCollection}
features: {type: array, items: {type: object}}
meta: {$ref: '#/components/schemas/Meta'}
links: {$ref: '#/components/schemas/Links'}- The
x-…extensions are the project's own:x-scope,x-source-families,x-cache-family,x-stability,x-mcp-counterpart,x-extensible-enum. The governance lint (Spec: API Lifecycle and Governance) requires them. - Source family ids in the excerpt are illustrative.
- The excerpt is parsed as YAML by the specification's checks; it is not yet validated against a running implementation.
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