Repository navigation
Spec Data Governance
mavrovde edited this page Nov 1, 2026
·
2 revisions
Part of the Technical Specification. Requirement prefix: GOV. Covers the data the API itself holds or emits. The mobility data it serves is governed by Spec: Data Licensing and Attribution; its logical model and retention classes are on Data Model.
| Class | Meaning | Examples | Handling |
|---|---|---|---|
| Public | Meant for anyone | the OpenAPI document, /v1/sources, documentation |
No restriction |
| Licensed | Public data under licence terms | every data response | Licence gate, attribution, notes |
| Internal | Operational, not personal | aggregated metrics, deployment records, configuration without secrets | Operator access only |
| Personal | Relates to an identifiable person | key-holder name and contact, truncated client addresses in access logs, audit actor names | GDPR controls below |
| Secret | Compromise causes harm | API key secrets, the pepper, the cursor signing key, storage credentials | Never logged, never stored in clear, rotated |
| Data | Class | Where | Retention (design default) | Key |
|---|---|---|---|---|
| Key holder record (label, contact e-mail, organisation, plan) | Personal | access store | life of the key + 30 days, then anonymised | governance.keyholder_retention_days |
| Key MAC, key id | Secret / Internal | access store | life of the key + audit retention | |
| Audit records (lifecycle actions) | Personal (actor) | access store | 395 days | audit.retention_days |
| Hourly usage per key and operation | Internal (pseudonymous by key id) | access store | 400 days | metering.retention_days |
| Access log lines (truncated address, key id) | Personal | log sink | 7 days | log.retention_days |
| Per-IP limiter state (full address) | Personal | memory only | 10 minutes | ratelimit.ip_state_ttl |
| Traces (sampled, no parameters) | Internal | trace sink when enabled | 7 days | otel.retention_days |
| Terms acceptances | Personal (by key) | access store | life of the key + 3 years (evidence) | governance.acceptance_retention_days |
The record of processing activities (Art. 30) for the API holds these entries:
| Processing | Purpose | Legal basis | Categories | Recipients | Retention |
|---|---|---|---|---|---|
| Key administration | Provide and secure the service to the key holder | Art. 6(1)(b) contract | contact data of the key holder | none outside the operator | section 2 |
| Security and abuse prevention logs | Keep the service secure and available | Art. 6(1)(f) legitimate interest | truncated network address, key id, request metadata | none | 7 days |
| Usage metering | Enforce quotas, bill or report usage | Art. 6(1)(b) | key id, counts | none | 400 days |
| Terms acceptance evidence | Prove acceptance required by a data licence | Art. 6(1)(c) and (f) | key id, terms version, instant | none | section 2 |
| ID | Requirement | Verification |
|---|---|---|
| GOV-001 | Every stored data element MUST be in the inventory with a class, a location and a retention key; a new element requires an inventory update in the same pull request. | Review |
| GOV-002 | Retention MUST be enforced by automatic deletion or anonymisation, and the deletion job MUST be monitored. | Ops |
| GOV-003 | The record of processing activities MUST be maintained as above and reviewed with every change to section 2. | Review |
| GOV-004 | A data protection impact assessment (DPIA, Art. 35) MUST be carried out before any of the following: storing full client addresses beyond the limiter window, adding user accounts or self-service sign-up with identity data, profiling or analytics of key holders, serving any data about identifiable persons, or processing outside the EU. | Review |
| GOV-005 | Data subject requests (access, rectification, erasure) from key holders MUST be answered within one month; erasure revokes the key and anonymises its records except where retention is legally required. | Ops |
| GOV-006 | A personal data breach MUST be assessed at once and, where required, notified to the supervisory authority within 72 hours (Art. 33). | Ops |
| GOV-007 | Secrets MUST be rotatable without downtime: the pepper (SEC-011), the cursor signing key (a previous key accepted for pagination.cursor_ttl), storage credentials. |
Unit |
| GOV-008 | Processors (hosting, e-mail) MUST be bound by a data processing agreement (Art. 28) and located in the EU. | Review |
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