Repository navigation
Spec Scope and Conventions
Part of the Technical Specification. Requirement prefix: CONV.
This specification defines the externally observable behaviour of ViaFrei API v1: a public, keyed, read-only HTTP interface to live German mobility context, served at https://api.viafrei.de/v1 (see API Address). It covers the protocol, the resource model, the response envelope, errors, authentication, rate limiting, non-functional requirements, licensing, versioning, configuration and conformance, and the engineering process around them.
In scope: everything a client can observe on the wire, and every quality the operator commits to as a design target.
Out of scope:
- how the data the API serves is obtained. The API reads storage it does not own, through a published read contract (see Architecture Overview); nothing in this specification describes or depends on how that storage is filled;
- the implementation language and libraries (the stack is open, see Stack Comparison);
- route computation (a non-goal, see Vision and Goals);
- write operations of any kind; push delivery (webhooks, server-sent events) in v1.
Status. This is a design specification. Every number in it is a design target or an assumption, never a measurement. There is no running API yet (Project Status).
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in capitals.
- "The service" is the ViaFrei API implementation. "The client" is any software calling it. "The operator" runs the service.
- A requirement without a named subject applies to the service.
- An implementation conforms to this specification when it satisfies every MUST and MUST NOT that applies to it. A deviation from a SHOULD is recorded with its reason in an architecture decision record (Spec: Architecture Decisions).
Every normative statement carries a stable identifier <PREFIX>-<NNN> (for example FR-ROAD-003, NFR-PERF-001, SEC-012), so issues, pull requests and tests can cite it.
- An identifier is never reused. A withdrawn requirement keeps its row, marked withdrawn, with the reason.
- A changed requirement keeps its identifier if its intent is unchanged; otherwise it is withdrawn and a new identifier is issued.
- Each requirement row names its verification method from this list: Unit, Handler, Contract (OpenAPI conformance), Mapping (storage translation), Parity (same facts as the MCP counterpart), Load, Security, Config, Lint, Docs (documentation check), Review, Ops (operational evidence).
- The Spec: Traceability Matrix lists every identifier with its page, its method and its planned test.
The project glossary is Glossary. The terms below are used normatively in this specification.
| Term | Definition |
|---|---|
| Operation | One HTTP method on one path template, identified by an operationId in the OpenAPI document |
| Feature | A client question answered by one or more operations, for example "conditions along a motorway" |
| Simple feature | A feature served by one read port |
| Composed feature | A feature that combines several read ports in one answer, for example the route briefing |
| Part | One component of a composed answer, with its own status |
| Source family | A group of data sources with the same licence treatment; the unit of attribution and of the licence gate |
| Freshness | The age of the newest data of a source family at the moment of the answer |
| Instant | A point on the UTC time line |
| Local rendering | The same instant written with the Europe/Berlin offset valid at that instant |
| Design target | A required property that tests check; not a measurement |
| Assumption | A belief the design depends on that is not yet confirmed; listed on [[Spec: Risks, Assumptions and Constraints |
| ID | Requirement | Verification |
|---|---|---|
| CONV-001 | Every payload MUST be valid JSON (RFC 8259), encoded as UTF-8 without a byte order mark. | Contract |
| CONV-002 | JSON member names MUST be English camelCase. Enumeration values MUST be lower snake_case strings. Query parameter names MUST be lower snake_case. | Lint |
| CONV-003 | An instant MUST be an RFC 3339 date-time in UTC with the Z designator and at most millisecond precision, for example 2026-11-01T13:05:00Z. |
Contract |
| CONV-004 | Where an instant is shown to people (departures, validity windows, observation times), the object MUST also carry the local rendering in a sibling field named <field>Local, an RFC 3339 date-time with the Europe/Berlin offset valid at that instant, for example 2026-11-01T14:05:00+01:00. Both fields denote the same instant. |
Unit |
| CONV-005 | A calendar date without time MUST be an RFC 3339 full-date interpreted in Europe/Berlin. A duration in a parameter MUST be an integer with its unit in the name (duration_min), never an ISO 8601 duration string. |
Contract |
| CONV-006 | Every dimensioned number MUST carry its unit as a suffix of the field or parameter name: M metres, Km kilometres, Kw kilowatts, Min minutes, S seconds, C degrees Celsius, Pct percent. Distances between points MUST be integer metres (distanceM). Road positions (chainage) MUST be kilometres with at most one decimal (fromKm), matching road signage. |
Lint |
| CONV-007 | Monetary amounts MUST be objects {"amount": "<decimal string>", "currency": "<ISO 4217 code>"}. The amount MUST be a decimal string with a dot separator and the precision published by the source (fuel prices carry three decimals). Binary floating point MUST NOT be used for money at any point. |
Unit |
| CONV-008 | Coordinates MUST use WGS 84 (EPSG:4326) in decimal degrees with at most six decimals. A point in JSON MUST be {"lat": <number>, "lon": <number>}. In GeoJSON (RFC 7946) positions are [lon, lat] as the standard requires. The at query parameter is written lat,lon. A bounding box parameter is written min_lon,min_lat,max_lon,max_lat as in RFC 7946 section 5. |
Contract |
| CONV-009 | Language tags MUST be BCP 47 tags. German (de) is the default; English (en) MUST be supported; further languages MAY be added without a version change. |
Handler |
| CONV-010 | Resource identifiers MUST be opaque strings with a type prefix (pl_ place, ad_ address, poi_ point of interest, jn_ junction, rs_ road situation, fs_ fuel stop, cs_ charging site, pk_ parking site, sh_ sharing station, sp_ stop place, ds_ disruption, fc_ facility, ww_ weather warning). Clients MUST NOT parse them. An identifier MUST NOT encode a storage key, a table name or a source name. |
Lint |
| CONV-011 | Road references MUST use the official national designation without spaces, upper case (A8, A100, B27); input MUST be accepted case-insensitively and with an optional space (a 8). |
Unit |
| CONV-012 | Booleans MUST be JSON booleans; a tri-state fact (yes, no, unknown) MUST be an enumeration, never a nullable boolean. | Review |
| CONV-013 | Country and region codes, where present, MUST be ISO 3166-1 alpha-2 and ISO 3166-2 (DE-BY). |
Contract |
| Reference | Used for |
|---|---|
| RFC 2119, RFC 8174 (BCP 14) | Requirement keywords |
| RFC 9110 HTTP Semantics | Methods, status codes, content negotiation, conditional requests |
| RFC 9111 HTTP Caching |
Cache-Control, freshness, validation |
| RFC 9112, RFC 9113 | HTTP/1.1 and HTTP/2 message syntax and framing |
| RFC 8446, RFC 5246 | TLS 1.3 and TLS 1.2 |
| RFC 6797 | HTTP Strict Transport Security |
| RFC 9457 | Problem details for HTTP APIs |
| RFC 8259 | JSON |
| RFC 7946 | GeoJSON |
| RFC 3339 | Timestamps |
| ISO 8601-1:2019 | Date and time representation (RFC 3339 is a profile) |
| RFC 6750 | Bearer token usage |
| OpenAPI Specification 3.1.x, JSON Schema 2020-12 | Interface description |
| RFC 9239 | Media types for JavaScript (text/javascript for the documentation portal's scripts) |
| RFC 8288 | Web linking (Link header, relation types) |
| RFC 8594 | The Sunset header |
| RFC 9745 | The Deprecation header |
| draft-ietf-httpapi-ratelimit-headers |
RateLimit-Policy and RateLimit (tracked; the draft revision implemented is pinned in the OpenAPI document) |
| RFC 9651 | Structured field values for HTTP |
| RFC 9110 section 10.2.3 | Retry-After |
| W3C Trace Context Level 1 |
traceparent, tracestate
|
| W3C CORS as specified in the WHATWG Fetch Standard | Cross-origin access |
| ISO 4217 | Currency codes |
| ISO 3166-1, ISO 3166-2 | Country and subdivision codes |
| BCP 47 (RFC 5646, RFC 4647) | Language tags and matching |
| RFC 9562 | Universally unique identifiers (time-ordered request identifiers) |
| WCAG 2.2 | Accessibility of the documentation portal |
| Regulation (EU) 2016/679 (GDPR) | Personal data handling |
Informative guides the specification draws on are listed in the Technical Specification index.
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