Skip to content

Spec Common Envelope

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Common Envelope

Part of the Technical Specification. Requirement prefix: ENV. This page refines the response shape on API Design.

1. Structure

Every successful JSON data response is one object with three members:

{
  "data": { },
  "meta": { },
  "links": { }
}
  • data holds the answer: an object for a single resource or a composed answer, an array for a list.
  • meta holds provenance, freshness, paging, language and warnings.
  • links holds absolute URLs related to this response.

1.1 meta

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)

1.2 meta.freshness[]

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

1.3 links

self (always), next (when there is a further page), sources (the source register), docs (the operation's reference page).

1.4 Complete example

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

2. GeoJSON variant

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

3. Pagination

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

4. Filtering, sorting and field selection

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

5. Null, absent and empty

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

6. Enumerations and extensibility

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

7. Deprecation signals

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally