Skip to content

Spec OpenAPI Skeleton

mavrovde edited this page Nov 1, 2026 · 1 revision

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'}

Notes on the excerpt

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally