Skip to content

Spec Scope and Conventions

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Scope, Conventions and References

Part of the Technical Specification. Requirement prefix: CONV.

1. Scope

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).

2. Conformance language

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).

3. Requirement identifiers

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.

4. Glossary (specification terms)

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

5. Data conventions

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

6. Normative references

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally