openapi: 3.0.3
info:
  title: HydroDaten API Standard - Erweitert
  version: '1.0_20260416'
  description: >-
    Diese OpenAPI-Spezifikation für hydrologische Daten des Projekts "HydroDaten API Standard (HyDAS)" dient als Muster für die Implementierung von Datenschnittstellen (öffentlich oder kundenspezifisch) in den deutschen Bundesländern, Bundesinstitutionen und weiteren Datenanbietern. Sie legt grundlegende Strukturen und Konventionen zur Bereitstellung hydrologischer Messdaten (z.B. Wasserstände) fest und bildet die technische Basis für zukünftige fachliche Erweiterungen, etwa in den Bereichen Niederschlag und Wasserqualität. Bei Bedarf kann sie weiter präzisiert werden.


    Dies ist die erweiterte Variante von HyDAS mit allen Endpunkten, Query-Parametern, Ausgabeformaten, Authentifizierung, Caching und weiteren Features. Für einen vereinfachten Einstieg steht die Basis-Variante mit nur 3 Endpunkten zur Verfügung.

    ## Hintergrund  

    Der Bedarf nach einer bundesweiten Bereitstellung aktueller hydrologischer Pegel-Messwerte, insbesondere Wasserstände, ist groß und durch gesetzliche Vorgaben gestützt. Die föderale Zuständigkeit erschwert den Zugriff auf diese Daten, da sie von jedem Bundesland anders erfasst werden. Eine zentrale Anlaufstelle für Pegeldaten fehlt, was den Zugang kompliziert.


    Um den Kunden und den Datenaustausch zwischen Bundesländern zu erleichtern, wurde die Idee einer einheitlichen Spezifikation entwickelt. Diese definiert Struktur, Benennung und Antwortformate und richtet sich an alle Bundesländer und Datenanbieter. Sie dient als Vorlage für die Umsetzung von Schnittstellen (REST-API) und soll breit angewendet werden. 


    Ziel ist es, den bundesweiten Zugang zu hydrologischen Daten zu vereinfachen und eine Grundlage für interoperable Fachanwendungen sowie den Datenaustausch zwischen Bund, Ländern und Dritten zu schaffen.


    Die Spezifikation entstand im Rahmen des Projekts "HydroDaten API", das Teilnehmer aus verschiedenen Bundesländern, Mitglieder der Bund/Länder-Arbeitsgemeinschaft (LAWA) und PEGELONLINE (Wasserstraßen- und Schifffahrtsverwaltung des Bundes) umfasst.

    ## Verwendung

    Die Spezifikation definiert Endpunkte, Datenstrukturen und Antwortformate. Sie dient zur Implementierung, Validierung und Dokumentation von Schnittstellen, die diesem Standard entsprechen. Zudem eignet sich die Spezifikation zur Validierung entwickelter APIs sowie zur Erstellung von Client- und Server-Stubs, die den Standard ebenfalls erfüllen.


    Weitere Informationen finden Sie in der [API-Guideline](https://dev.hochwasserzentralen.de/hydrodaten-api/guide) zur Verwendung des HydroDaten API Standards.
  x-logo:
    url: ''
servers:
- url: https://dev.hochwasserzentralen.de/hydrodaten-api/demo/v1
  description: ''
  x-last-modified: 1758746582337
paths:
  /:
    get:
      summary: API-Root und Service-Discovery
      description: >-
        Gibt Metadaten über die API und Links zu verfügbaren Hauptressourcen zurück. Dieser Endpunkt dient der Service-Discovery und ermöglicht Clients, die verfügbaren Ressourcen programmatisch zu erkunden (HATEOAS-Prinzip). Ist optional.
      operationId: getApiRoot
      tags:
      - API-Metadaten
      security:
      - {}
      responses:
        '200':
          description: API-Root mit Links zu Hauptressourcen
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - links
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Links zu den Hauptressourcen der API. Clients können diese Links nutzen, um die API zu erkunden ohne URLs hart zu codieren.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/
                      types:
                      - application/json
                    - rel: stations
                      href: https://api.example.io/v1/stations
                      types:
                      - application/json
                    - rel: health
                      href: https://api.example.io/v1/health
                      types:
                      - application/json
                    - rel: openapi
                      href: https://api.example.io/v1/openapi.yaml
                      types:
                      - application/yaml
                      - application/json
                    - rel: documentation
                      href: https://dev.hochwasserzentralen.de/hydrodaten-api/
                      types:
                      - text/html
              example:
                meta:
                  title: Projekt HydroDaten API
                  version: 1.0.0
                  description: API für hydrologische Stationsdaten, Mess- und Kennwerte
                  descriptionUrl: https://dev.hochwasserzentralen.de/hydrodaten-api/
                  baseUrl: https://api.example.io/v1
                  publisherName: Hochwasservorhersagezentrale Baden-Württemberg
                  publisherEmail: kontakt@hvz-bw.de
                  licenseName: CC BY 4.0
                  licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
                links:
                - rel: self
                  href: https://api.example.io/v1/
                  types:
                  - application/json
                - rel: stations
                  href: https://api.example.io/v1/stations
                  types:
                  - application/json
                - rel: health
                  href: https://api.example.io/v1/health
                  types:
                  - application/json
                - rel: openapi
                  href: https://api.example.io/v1/openapi.yaml
                  types:
                  - application/yaml
                  - application/json
                - rel: documentation
                  href: https://dev.hochwasserzentralen.de/hydrodaten-api/
                  types:
                  - text/html
        '500':
          $ref: '#/components/responses/InternalServerError'
  /health:
    get:
      summary: Health Check
      description: >-
        Gibt den Gesundheitsstatus der API und ihrer Abhängigkeiten zurück. Dieser Endpunkt kann von Load Balancern (zur Erkennung ausgefallener API-Instanzen und Umleitung auf gesunde Instanzen),  Container-Orchestrierung (Kubernetes), Monitoring-Systemen (zur kontinuerlichen Überwachung der API-Verfügbarkeit) oder CI/CD-Pipelines (Validierung nach Deployments) verwendet werden.


        **HTTP Status Codes:**

        - 200: API ist vollständig betriebsbereit (status: healthy)

        - 503: API ist nicht verfügbar oder eingeschränkt funktionsfähig (status: degraded oder unhealthy)


        **Implementierungshinweise:**

        - Antwortzeit MUSS unter 1 Sekunde liegen (ideal: < 100ms)

        - Wenn möglich kritische Komponenten prüfen (Datenbank, Cache, Verfügbarkeit externe APIs und Services, usw.), also kein reinen PING-Endpunkt definieren

        - optional Unterscheidung zwischen "degradiert" (teilweise funktionsfähig) und "ausgefallen"

        - Keine Authentifizierung erforderlich (muss auch bei Auth-Ausfall funktionieren) oder nur einfache Authentifizierungsmethode 

        - Keine Caching-Header verwenden (Echtzeit-Status erforderlich)

        - Das `message` Feld SOLLTE bei Problemen konkrete Informationen liefern

        - Keine sensiblen Informationen im message-Feld 
                
        - Implementierer KÖNNEN zusätzliche Felder hinzufügen


        **Fokus:** Health Check beantwortet die Frage "Kann diese API Anfragen verarbeiten?"

      operationId: getHealth
      tags:
      - API-Metadaten
      security:
      - {}
      responses:
        '200':
          description: API ist betriebsbereit und kann Anfragen verarbeiten
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
              examples:
                healthy:
                  summary: Vollständig betriebsbereit
                  description: Alle Systeme funktionieren normal
                  value:
                    status: healthy
                    message: API betriebsbereit
                    timestamp: '2025-12-17T10:30:00+01:00'
                    uptime: 86400
                degraded:
                  summary: Eingeschränkt betriebsbereit
                  description: API funktioniert, aber mit Einschränkungen (z.B. Cache ausgefallen)
                  value:
                    status: degraded
                    message: API-Responsezeiten verlangsamt
                    timestamp: '2025-12-17T10:30:00+01:00'
                    uptime: 86400
        '503':
          description: API ist nicht verfügbar oder stark beeinträchtigt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
              examples:
                unhealthy:
                  summary: Nicht betriebsbereit
                  description: Kritische Komponente ausgefallen, API kann keine Anfragen verarbeiten
                  value:
                    status: unhealthy
                    message: API nicht betriebsbereit
                    timestamp: '2025-12-17T10:30:00+01:00'
                    uptime: 86400
  /stations:
    get:
      summary: Liste von Messstationen
      description: Gibt eine Liste der Messstationen zurück (Oberflächengewässermessstationen, Grundwassermessstationen oder Meteorologische Messstationen).
      operationId: getStations
      tags:
      - Stationen
      parameters:
      - name: ids
        in: query
        required: false
        description: Filtert nach mehreren Messstations-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: waterBodyIds
        in: query
        required: false
        description: Filtert nach Gewässer-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: operators
        in: query
        required: false
        description: Filtert nach Messstellenbetreibern (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: states
        in: query
        required: false
        description: Filtert nach Bundeslandkürzeln (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: parameterIds
        in: query
        required: false
        description: >-
          Filtert nach Parametern: liefert nur Stationen, die einen der angegebenen Parameter führen (kommagetrennt). Wird zusätzlich noch `include=parameters` angegeben, wird nur der jeweilige Parameter eingebettet.
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: bbox
        in: query
        required: false
        description: >-
          Geografische Bounding Box für räumliche Filterung. Format: minLon,minLat,maxLon,maxLat (kommagetrennt). Liefert nur Stationen, deren Koordinaten innerhalb der angegebenen Bounding Box liegen. Beispiel: 8.0,47.0,9.0,48.0 für den Bereich zwischen 8°-9° Ost und 47°-48° Nord.
        schema:
          type: array
          items:
            type: number
          minItems: 4
          maxItems: 4
        style: form
        explode: false
      - name: near
        in: query
        required: false
        description: >-
          Umkreissuche um einen geografischen Punkt. Format: lon,lat,radius (kommagetrennt). Liefert nur Stationen innerhalb des angegebenen Radius um den Punkt. Der Radius wird in Kilometern angegeben. Beispiel: 8.5,47.5,50 für alle Stationen im Umkreis von 50km um 8.5° Ost, 47.5° Nord.
        schema:
          type: array
          items:
            type: number
          minItems: 3
          maxItems: 3
        style: form
        explode: false
      - name: include
        in: query
        required: false
        description: >-
          Optionale Einbettung von Parametern (`parameters`), Kennwerten (`characteristics`) oder Werten (`values`) in die Serverantwort  (Mehrfachangaben möglich als kommagetrennte Liste). Werden die Werten (`values`) eingebettet macht es Sinn noch die Query-Parameter `from`, `to`, `last` oder `recent` anzubieten und zu verarbeiten (siehe "Werte abrufen").
        schema:
          type: array
          items:
            type: string
            enum:
            - parameters
            - characteristics
            - values
          uniqueItems: true
        style: form
        explode: false
      - name: limit
        in: query
        required: false
        description: >-
          Maximale Anzahl der zurückzugebenden Stationen pro Seite.
        schema:
          type: integer
          minimum: 1
          maximum: 10000
          example: 100
      - name: offset
        in: query
        required: false
        description: >-
          Anzahl der zu überspringenden Stationen (Offset für Mehrseitigkeit). Standardwert ist 0. Wird in Kombination mit limit verwendet, um durch große Ergebnismengen zu navigieren.
        schema:
          type: integer
          minimum: 0
          default: 0
          example: 0
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/SortParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Liste der Messstationen
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Für den Stations-Listenendpunkt werden hauptsächlich URI Templates verwendet, da die unterschiedlichen IDs in den einzelnen Stationen enthalten sind. Bei seitenweisen Antworten enthalten die Links auch Navigationsbeziehungen (first, next, prev, last).
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations?limit=100&offset=0
                    - rel: first
                      href: https://api.example.io/v1/stations?limit=100&offset=0
                    - rel: next
                      href: https://api.example.io/v1/stations?limit=100&offset=100
                    - rel: last
                      href: https://api.example.io/v1/stations?limit=100&offset=2800
                    - rel: station
                      href: https://api.example.io/v1/stations/{stationId}
                    - rel: parameters
                      href: https://api.example.io/v1/stations/{stationId}/parameters
                    - rel: values
                      href: https://api.example.io/v1/stations/{stationId}/parameters/{parameterId}/values
                    - rel: characteristics
                      href: https://api.example.io/v1/stations/{stationId}/characteristics
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/SurfaceWaterStation'
                      - $ref: '#/components/schemas/GroundwaterStation'
                      - $ref: '#/components/schemas/MeteorologicalStation'
                      discriminator:
                        propertyName: type
                        mapping:
                          surfaceWater: '#/components/schemas/SurfaceWaterStation'
                          groundwater: '#/components/schemas/GroundwaterStation'
                          meteorological: '#/components/schemas/MeteorologicalStation'
            text/csv:
              schema:
                type: string
              example: |
                id,name,type,state,operator,coordinates.lat,coordinates.lon,waterBodyId,waterBodyName
                a0af41ce-1899-4192-bc70-2fe66581bc8b,Teststation,surfaceWater,DE-BW,Regierungspräsidium xy,52.5163,13.3777,2,Rhein,true
                b1bf52df-2900-5203-cd81-3gf77692cd9c,Grundwasserstation Berlin,groundwater,DE-BE,Senatsverwaltung,52.5200,13.4050,,,true
            application/geo+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum: [ FeatureCollection ]
                  features:
                    type: array
                    items:
                      type: object
              example:
                type: FeatureCollection
                features:
                - type: Feature
                  geometry:
                    type: Point
                    coordinates: [ 13.3777, 52.5163 ]
                  properties:
                    id: a0af41ce-1899-4192-bc70-2fe66581bc8b
                    name: Teststation
                    type: surfaceWater
                    state: DE-BW
                    operator: Regierungspräsidium xy
                    waterBodyId: "2"
                    waterBodyName: Rhein
                - type: Feature
                  geometry:
                    type: Point
                    coordinates: [ 13.4050, 52.5200 ]
                  properties:
                    id: b1bf52df-2900-5203-cd81-3gf77692cd9c
                    name: Grundwasserstation Berlin
                    type: groundwater
                    state: DE-BE
                    operator: Senatsverwaltung
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}:
    get:
      summary: Einzelne Messstation abrufen
      description: Gibt detaillierte Informationen zu einer spezifischen Messstation zurück
      operationId: getStationById
      tags:
      - Stationen
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: include
        in: query
        required: false
        description: >-
          Optionale Einbettung von Parametern (`parameters`), Kennwerten (`characteristics`) oder Werten (`values`) in die Serverantwort (Mehrfachangaben möglich als kommagetrennte Liste). Werden die Werten (`values`) eingebettet, ist es empfehlenswert die Query-Parameter `from`, `to`, `last` oder `recent` anzubieten und zu verarbeiten (siehe "Werte abrufen")
        schema:
          type: array
          items:
            type: string
            enum:
            - parameters
            - characteristics
            - values
          uniqueItems: true
        style: form
        explode: false
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Details der Messstation
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Beim Stations-Endpunkte können direkte URIs verwendet werden, da die spezifische stationId bekannt ist. Nur für weiterführende Ressourcen, die zusätzliche IDs benötigen (z.B. parameterId), werden URI Templates genutzt.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                    - rel: parameters
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters
                    - rel: values
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/{parameterId}/values
                    - rel: characteristics
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/characteristics
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/SurfaceWaterStation'
                    - $ref: '#/components/schemas/GroundwaterStation'
                    - $ref: '#/components/schemas/MeteorologicalStation'
                    discriminator:
                      propertyName: type
                      mapping:
                        surfaceWater: '#/components/schemas/SurfaceWaterStation'
                        groundwater: '#/components/schemas/GroundwaterStation'
                        meteorological: '#/components/schemas/MeteorologicalStation'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/parameters:
    get:
      summary: Liste aller Parameter einer Messstation
      description: Gibt eine Liste aller verfügbaren Messparameter einer Messstation zurück.
      operationId: getStationParameters
      tags:
      - Parameter
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: ids
        in: query
        required: false
        description: Filtert nach Parameter-IDs (kommagetrennt)
        schema:
          type: array
          items:
            type: string
          uniqueItems: true
        style: form
        explode: false
      - name: include
        in: query
        required: false
        description: >-
          Optionale Einbettung von Werten (`values`) in die Serverantwort. Es ist empfehlenswert, dann die Query-Parameter `from`, `to`, `last` oder `recent` anzubieten und zu verarbeiten (siehe "Werte abrufen")
        schema:
          type: array
          items:
            type: string
            enum:
            - values
          uniqueItems: true
        style: form
        explode: false
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/SortParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Liste der Parameter
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Die stationId ist vorgegeben (aus der HTTP-Anfrage), daher sind Links zur Station direkt. Für Werte wird ein URI Template verwendet, da die parameterId erst aus den Daten-Objekten bekannt ist.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters
                    - rel: station
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                    - rel: values
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/{parameterId}/values
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      $ref: '#/components/schemas/Parameter'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/parameters/{parameterId}:
    get:
      summary: Einzelnen Parameter abrufen
      description: Gibt detaillierte Informationen zu einem spezifischen Messparameter zurück
      operationId: getStationParameterById
      tags:
      - Parameter
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: parameterId
        in: path
        required: true
        description: Eindeutige Kennung des Parameters
        schema:
          type: string
          example: water-level-rel-15min
      - name: include
        in: query
        required: false
        description: >-
          Optionale Einbettung von Werten (`values`) in die Serverantwort. Es ist empfehlenswert, dann die Query-Parameter `from`, `to`, `last` oder `recent` anzubieten und zu verarbeiten (siehe "Werte abrufen")
        schema:
          type: array
          items:
            type: string
            enum:
            - values
          uniqueItems: true
        style: form
        explode: false
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Details des Parameters
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Alle IDs (stationId und parameterId) sind aus der HTTP-Abfrage bekannt, daher werden nur direkte URIs verwendet.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min
                    - rel: station
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                    - rel: values
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values
                  data:
                    $ref: '#/components/schemas/Parameter'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/parameters/{parameterId}/values:
    get:
      summary: Werte abrufen
      description: Gibt eine Zeitreihe von Messwerten oder Vorhersagen für einen Parameter zurück. Unterstützt Filterung nach Zeitraum.
      operationId: getParameterValues
      tags:
      - Werte
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: parameterId
        in: path
        required: true
        description: Eindeutige Kennung des Parameters
        schema:
          type: string
          example: water-level-rel-15min
      - name: from
        in: query
        required: false
        description: >-
          Startzeitpunkt der auszuliefernden Werte im ISO 8601 Format (inkl. Zeitzone), z. B. 2025-01-01T00:00:00+01:00
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        description: >-
          Endzeitpunkt der auszuliefernden Werte im ISO 8601 Format (inkl. Zeitzone), z. B. 2025-01-31T23:59:59+01:00
        schema:
          type: string
          format: date-time
      - name: last
        in: query
        required: false
        description: >-
          ISO-8601 Duration (z.B. P1D, PT24H), um Werte bis jetzt für diese Dauer zu liefern
        schema:
          type: string
          format: duration
      - name: recent
        in: query
        required: false
        description: >-
          Anzahl der neuesten Werte, die zurückgegeben werden sollen (z.B. recent=5)
        schema:
          type: integer
          minimum: 1
      - name: limit
        in: query
        required: false
        description: >-
          Maximale Anzahl der zurückzugebenden Werte pro Seite. Wird in Kombination mit den zeitlichen Filtern (from/to/last/recent) verwendet, um innerhalb des Zeitfensters zu paginieren.
        schema:
          type: integer
          minimum: 1
          maximum: 10000
          example: 1000
      - name: offset
        in: query
        required: false
        description: >-
          Anzahl der zu übersprungenen Werte (Offset für Paginierung innerhalb des Zeitfensters). Wird in Kombination mit limit verwendet, um durch große Zeitreihen zu navigieren.
        schema:
          type: integer
          minimum: 0
          example: 0
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/SortParameter'
      - name: format
        in: query
        required: false
        description: >-
          Gewünschtes Ausgabeformat für die Response. Dieser Parameter überschreibt den Accept-Header, falls beide angegeben sind. Ermöglicht einfaches Testen und Teilen von formatierten URLs. Standard ist JSON, wenn weder format-Parameter noch Accept-Header angegeben sind. Das Format `application/vnd.hydrodaten.compact+json` liefert eine kompakte Darstellung als reines Zahlenarray, bei dem sich die Zeitstempel aus Zeitbereich und Intervall ergeben. Dieses Format eignet sich für äquidistante Zeitreihen und reduziert die Datenmenge.
        schema:
          type: string
          enum:
          - application/json
          - application/vnd.hydrodaten.compact+json
          - text/csv
          - application/xml
          - application/geo+json
          default: application/json
        example: 'application/json'
      - name: Accept
        in: header
        required: false
        description: >-
          Gewünschtes Antwortformat via HTTP Content Negotiation (RESTful Standard). Der format Query-Parameter hat Vorrang, falls beide angegeben sind. Das Format `application/vnd.hydrodaten.compact+json` liefert eine kompakte Darstellung als reines Zahlenarray, bei dem sich die Zeitstempel aus Zeitbereich und Intervall ergeben. Dieses Format eignet sich für äquidistante Zeitreihen und reduziert die zu übertragene Datenmenge.
        schema:
          type: string
          enum:
          - application/json
          - application/vnd.hydrodaten.compact+json
          - text/csv
          - application/xml
          - application/geo+json
          default: application/json
        example: 'application/json'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Zeitreihe von Messwerten
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Alle IDs (stationId und parameterId) sind aus dem Pfad bekannt, daher werden nur direkte URIs verwendet. Bei paginierten Antworten enthalten die Links auch Paginierungs-Relationen (first, next, prev, last).
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?from=2025-01-01T00:00:00+01:00&to=2025-01-31T23:59:59+01:00&limit=1000&offset=0
                    - rel: first
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?from=2025-01-01T00:00:00+01:00&to=2025-01-31T23:59:59+01:00&limit=1000&offset=0
                    - rel: next
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?from=2025-01-01T00:00:00+01:00&to=2025-01-31T23:59:59+01:00&limit=1000&offset=1000
                    - rel: last
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min/values?from=2025-01-01T00:00:00+01:00&to=2025-01-31T23:59:59+01:00&limit=1000&offset=5000
                    - rel: station
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                    - rel: parameter
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/parameters/water-level-rel-15min
                  data:
                    oneOf:
                    - type: array
                      title: Wert mit Zeitstempel
                      description: Standard-Darstellung als Array von Werten mit Zeitstempeln
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/Value'
                    - type: array
                      title: Vorhersagewerte
                      description: Standard-Darstellung als Array von Vorhersagen mit Zeitstempeln
                      uniqueItems: true
                      items:
                        $ref: '#/components/schemas/Forecast'
              examples:
                default:
                  summary: Standard-Darstellung (format=application/json)
                  value:
                    meta:
                      title: Projekt HydroDaten API
                      version: 1.0.0
                      publisherName: Beispiel-Landesamt
                      licenseName: dl-de/by-2-0
                      licenseUrl: https://www.govdata.de/dl-de/by-2-0
                    data:
                      - timestamp: '2025-01-27T12:00:00+01:00'
                        value: 287
                      - timestamp: '2025-01-27T12:15:00+01:00'
                        value: 289
                      - timestamp: '2025-01-27T12:30:00+01:00'
                        value: 291
            application/vnd.hydrodaten.compact+json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/Link'
                  data:
                    $ref: '#/components/schemas/ValueArray'
              examples:
                compact:
                  summary: Kompakte Darstellung (format=application/vnd.hydrodaten.compact+json)
                  value:
                    meta:
                      publisher: Beispiel-Landesamt
                      license: dl-de/by-2-0
                      version: '0.1'
                    data:
                      from: '2025-01-27T00:00:00+01:00'
                      interval: 'PT15M'
                      values: [ 287, 289, null, 291, 293, 295 ]
            text/csv:
              schema:
                type: string
              example: |
                timestamp,value,quality
                2025-01-27T12:00:00+01:00,287,good
                2025-01-27T12:15:00+01:00,289,good
                2025-01-27T12:30:00+01:00,291,good
                2025-01-27T12:45:00+01:00,293,good
                2025-01-27T13:00:00+01:00,295,good
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/characteristics:
    get:
      summary: Liste aller Kennwerte einer Messstation
      description: Gibt eine Liste der statistischen Kennwerte, abgeleiteter Maßzahlen, gewässerkundlichen Hauptwerten oder Wasserstandsmarken einer Messstation zurück
      operationId: getStationCharacteristics
      tags:
      - Kennwerte
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/SortParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Liste der Kennwerte
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Die stationId ist bekannt (aus dem Pfad), daher ist der Link zur Station direkt.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/characteristics
                    - rel: station
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                  data:
                    type: array
                    uniqueItems: true
                    items:
                      $ref: '#/components/schemas/Characteristic'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /stations/{stationId}/characteristics/{characteristicId}:
    get:
      summary: Einzelnen Kennwert abrufen
      description: Gibt detaillierte Informationen zu einem spezifischen Kennwert zurück
      operationId: getStationCharacteristicById
      tags:
      - Kennwerte
      parameters:
      - name: stationId
        in: path
        required: true
        description: Eindeutige Kennung der Messstation (UUID)
        schema:
          type: string
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
      - name: characteristicId
        in: path
        required: true
        description: Eindeutige Id des Kennwerts
        schema:
          type: string
          example: discharge-mean-summer
      - $ref: '#/components/parameters/FieldsParameter'
      - $ref: '#/components/parameters/FormatParameter'
      - $ref: '#/components/parameters/AcceptHeader'
      - $ref: '#/components/parameters/AcceptEncodingHeader'
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          description: Antwort mit Details des Kennwerts
          headers:
            Cache-Control:
              $ref: '#/components/headers/CacheControlHeader'
            ETag:
              $ref: '#/components/headers/ETagHeader'
          content:
            application/json:
              schema:
                type: object
                required:
                - meta
                - data
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
                  links:
                    type: array
                    description: >-
                      Optionale Link-Liste zu verknüpften Ressourcen. Alle IDs (stationId und characteristicId) sind aus dem Pfad bekannt, daher werden nur direkte URIs verwendet.
                    items:
                      $ref: '#/components/schemas/Link'
                    example:
                    - rel: self
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/characteristics/discharge-mean-summer
                    - rel: station
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
                    - rel: characteristics
                      href: https://api.example.io/v1/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b/characteristics
                  data:
                    $ref: '#/components/schemas/Characteristic'
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Meta:
      description: Metadaten-Block mit allgemeinen Informationen. Für jede API-Response erforderlich.
      type: object
      required:
      - title
      - version
      - publisherName
      - licenseName
      - licenseUrl
      properties:
        title:
          type: string
          description: Titel/Name der API oder des Responses
          example: Projekt HydroDaten API
        version:
          type: string
          description: Versionsnummer der API
          example: 1.0.0
        description:
          type: string
          description: Prägnante, aber informative Beschreibung der API oder des Responses (Beschreibung der Daten in Abschnitt `data`)
          example: API für hydrologische Stationsdaten, Mess- und Kennwerte
        descriptionUrl:
          type: string
          description: URL zur Beschreibung der API
          example: https://dev.hochwasserzentralen.de/hydrodaten-api/
        baseUrl:
          type: string
          description: Basis-URL der API
          example: https://api.example.io/v1
        publisherName:
          type: string
          description: Name der Organisation, die die API bereitstellt und veröffentlicht
          example: Hochwasservorhersagezentrale xy
        publisherEmail:
          type: string
          description: Emailadresse des Publishers
          example: kontakt@hochwasservorhersage.de
        licenseName:
          type: string
          description: Name der Daten-Lizenz
          example: CC BY 4.0
        licenseUrl:
          type: string
          description: URL zur Lizenzbeschreibung
          example: https://creativecommons.org/licenses/by/4.0/deed.de
        schemaUrl:
          type: string
          description: URL zur Schemadatei der Ressource
          example: https://api.example.io/v1/schema-stations.json
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: >-
            Optional: Paginierungsinformationen für Listen-Endpunkte. Wird nur bei paginierten Antworten (z.B. /stations, /parameters, /characteristics) ausgegeben.
    Link:
      description: >-
        Optionale Links zu verknüpften Ressourcen nach HATEOAS-Prinzip.


        Links können entweder direkte URIs oder URI Templates (nach RFC 6570) enthalten:

        - **URI Templates** enthalten Platzhalter in geschweiften Klammern (z.B. `{stationId}`) und werden typischerweise in Listen-Endpunkten verwendet (z.B. `/stations`)

        - **Direkte URIs** sind vollständig aufgelöste Links ohne Platzhalter und werden in Detail-Endpunkten verwendet (z.B. `/stations/{stationId}`)
      type: object
      required:
      - rel
      - href
      properties:
        rel:
          type: string
          description: >-
            Typ der verknüpften Ressource. Definiert die Beziehung zwischen der aktuellen Ressource und dem Link-Ziel:

            - `self`: Link zur aktuellen Ressource selbst

            - `station`: Link zu einer einzelnen Station

            - `parameters`: Link zu allen Parametern (Messreihen) einer Station

            - `parameter`: Link zu einem einzelnen Parameter (Messreihe)

            - `values`: Link zu Messwerten eines Parameters

            - `characteristics`: Link zu Kennwerten einer Station

            - `health`: Link zum Health-Check-Endpunkt

            - `documentation`: Link zur HTML Dokumentation

            - `openapi`: Link zur Open-API Spezifikation

            - `first`: Link zur ersten Seite einer paginierten Liste

            - `next`: Link zur nächsten Seite einer paginierten Liste

            - `prev`: Link zur vorherigen Seite einer paginierten Liste

            - `last`: Link zur letzten Seite einer paginierten Liste
          enum:
          - self
          - station
          - parameters
          - parameter
          - values
          - characteristics
          - health
          - documentation
          - openapi
          - first
          - next
          - prev
          - last
          example: parameters
        href:
          type: string
          description: >-
            URI oder URI Template (RFC 6570) zur verknüpften Ressource.

            URI Templates enthalten Variablen in geschweiften Klammern wie `{stationId}` oder `{parameterId}`, die durch konkrete Werte ersetzt werden müssen.
          example: https://api.example.io/v1/stations/{stationId}/parameters
        types:
          type: array
          description: Optionale Kennzeichnung der Repräsentationsformen der verknüpften Ressource.
          default:
          - application/json
          example:
          - application/json
          items:
            type: string
    Pagination:
      title: Mehrseitige Antworten (offset, limit)
      description: >-
        Metadaten bei mehrseitigen Listen-Ressourcen (`/stations`, `/values`). Ermöglicht Clients die Navigation durch große Datenmengen und die Anzeige von Fortschrittsinformationen.
      type: object
      properties:
        total:
          type: integer
          description: Gesamtanzahl der Elemente, die der Abfrage entsprechen (ohne Paginierung)
          example: 2847
        count:
          type: integer
          description: Anzahl der Elemente in der aktuellen Antwort
          example: 100
        limit:
          type: integer
          description: Maximale Anzahl der Elemente pro Seite (angefordert)
          example: 100
        offset:
          type: integer
          description: Anzahl der übersprungenen Elemente (Offset)
          example: 0
        page:
          type: integer
          description: Aktuelle Seitennummer (optional, zur Vereinfachung)
          example: 1
        totalPages:
          type: integer
          description: Gesamtanzahl der Seiten
          example: 29
        hasNextPage:
          type: boolean
          description: Gibt an, ob weitere Elemente verfügbar sind
          example: true
        hasPreviousPage:
          type: boolean
          description: Gibt an, ob eine vorherige Seite existiert
          example: false
    OperationalStatus:
      title: Betriebsstatus
      description: >-
        Informationen zum aktuellen Betriebsstatus einer Messstation oder eines Parameters.
      type: object
      required:
      - condition
      - message
      properties:
        condition:
          type: string
          description: >-
            Kennzeichnung des Betriebszustand: `operational` = normale Funktion, `impaired` = unspezifische allgemeine Form der Beeinträchtigung, `decommissioned` = nicht mehr in Betrieb. Auch spezifischere Formen der Beeinträchtigung können angegeben werden (z.B. `sensor-malfunction` = Sensorausfall oder `maintenance` = Wartungsarbeiten )
          enum:
          - operational
          - impaired
          - decommissioned
          - unavailable
          - degraded
          - sensor-malfunction
          - communication-failure
          - power-outage
          - maintenance
          - construction
          - calibration
          - data-quality
          - environmental
          - offline
          - other
          example: operational
        message:
          type: string
          description: Beschreibung des aktuellen Status, der Störung oder Wartungsarbeiten
          example: Wegen einer Funktionsstörung liefert die Station aktuell keine Messwerte.
        since:
          type: string
          format: date-time
          description: Zeitpunkt seit dem der aktuelle Status gilt
          example: '2025-01-15T08:30:00+01:00'
        expectedEnd:
          type: string
          format: date-time
          description: Voraussichtlicher Zeitpunkt der Behebung bei Störungen oder Ende der Wartungsarbeiten
          example: '2025-01-16T14:00:00+01:00'
        contact:
          type: string
          description: Kontaktinformation für aktuelle Messwerte oder Rückfragen bei Störungen (z.B. Telefonnummer, E-Mail)
          example: 'email@pegel.de'
    HealthStatus:
      title: API-Status
      description: >-
        Status (health status) der API und ihrer Komponenten. Wird vom `/health` Endpunkt zurückgegeben.
      type: object
      required:
      - status
      properties:
        status:
          type: string
          description: >-
            Gesamtstatus der API: - `healthy`: Alle Systeme funktionieren normal, API kann Anfragen verarbeiten - `degraded`: API funktioniert eingeschränkt (z.B. Cache ausgefallen, Datenbank langsam), kann aber noch Anfragen verarbeiten - `unhealthy`: API kann keine Anfragen verarbeiten (kritische Komponente ausgefallen)
          enum:
          - healthy
          - degraded
          - unhealthy
          example: healthy
        message:
          type: string
          description: >-
            Optionale Detailinformationen zum Status der API z.B. zur Verwendung als Message in Monitoring-Systemen. Achtung: Ist der Health-Endpoint öffentlich, dann keine sensiblen Informationen, technische Details, IP-Adressen usw. hier ausgeben.
        timestamp:
          type: string
          format: date-time
          description: Zeitpunkt der Health-Check-Durchführung im ISO 8601 Format mit Zeitzone
          example: '2025-12-17T10:30:00+01:00'
        uptime:
          type: integer
          description: Betriebszeit der API in Sekunden seit dem letzten Start
          example: 86400
    BaseStation:
      x-internal: true
      description: Basisschema mit gemeinsamen Attributen aller Messstationen
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Eindeutige unveränderliche Id der Messstelle zur Verwendung in URLs
          example: a0af41ce-1899-4192-bc70-2fe66581bc8b
        name:
          type: string
          description: Name der Messstelle
          example: Teststation
        number:
          type: string
          description: Nummer der Messstelle, wenn diese sich von der ID nochmal unterscheidet. Kann ggf. weggelassen werden.
          example: '123456'
        type:
          type: string
          description: "Haupttyp der Messstelle. 'surfaceWater' = Oberflächengewässermessstation, 'groundwater' = Grundwassermessstation, 'meteorological' = Meteorologische Messstation. Sollte unbedingt aufgeführt werden, wenn unterschiedliche Stationsarten an den  Stationen-Endpunkten zurückgeliefert werden können."
          enum:
          - surfaceWater
          - groundwater
          - meteorological
          example: surfaceWater
        state:
          type: string
          description: Kürzel des Bundeslandes nach ISO 3166-2:DE oder des Staates nach ISO-3166-1-Kodierliste
          example: DE-BW
        operator:
          type: string
          description: Name des Messstellenbetreibers
          example: Wasserstraßen- und Schifffahrtsamt (WSA) Rhein
        operatorUrl:
          type: string
          description: Webpräsenz des Messstellenbetreibers
          example: https://www.wsa-rhein.wsv.de/
        dataProvider:
          type: string
          description: Name des Datenbereitstellers
          example: LUBW Baden-Württemberg
        dataProviderUrl:
          type: string
          description: Webpräsenz des Datenbereitstellers
          example: https://www.lubw.baden-wuerttemberg.de
        url:
          type: string
          description: Direkte URL zur Messstelle
          example: https://hvz-example.io/messstelle-1.html
        status:
          $ref: '#/components/schemas/OperationalStatus'
        remarks:
          type: string
          description: Bemerkung zur Station (Freitext)
          example: Der Pegel liegt im Rückstau der Staustufe Bittenheim/Donau.
        gaugingNetwork:
          type: string
          description: Nennung des Namens des Messnetzes
          example: GW-Stand
        coordinates:
          type: object
          required:
          - lat
          - lon
          properties:
            lat:
              type: number
              description: Wert der geographischen Breite
              example: 52.5163
            lon:
              type: number
              description: Wert der geographische Höhe
              example: 13.3777
            epsgCode:
              type: integer
              description: EPSG-Code des Koordinatenreferenzsystems der Koordinaten. Standardwert ist WGS 84 (EPSG:4326), welcher die größte Kompatibilität gewährleistet. Wenn nicht angegeben, wird WGS 84 angenommen.
              default: 4326
              example: 4326
        referenceElevation:
          type: object
          description: Höhe bzw. Bezugshöhe einer Station, bei Pegeln i.d.R. der Pegelnullpunkt.
          required:
          - value
          properties:
            value:
              type: number
              description: Absolute Höhe, üblicherweise in Höhe über dem Meeresspiegel
            unit:
              type: string
              description: Einheit der Höhe entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
              example: m
            unitDisplay:
              type: string
              description: Benutzerfreundliche Anzeige der Höhe ggf. mit Bezug zum Höhensystem
              example: m NHN
            epsgCode:
              type: integer
              description: EPSG-Code des Höhensystems. Standardwert ist DHHN 2016 (EPSG:7837).
              default: 7837
              example: 7837
        municipalityCode:
          type: integer
          description: Gemeindeschlüssel, z.B. Amtlichen Gemeindeschlüssel (AGS)
          example: 9763000
        predecessorId:
          type: string
          description: Eindeutige Id der (stillgelegten) Vorgänger-Messstelle im selben räumlichen Bereich
          example: 3f4a8c10-9b2e-4c5f-8af1-12ab34cd56ef
        successorId:
          type: string
          description: Eindeutige Id der Nachfolger-Messstelle im selben räumlichen Bereich
          example: 3f445c10-9b2e-4c5f-8af1-12ad34cd56f1
        parameters:
          type: array
          description: Optional eingebettete Parameter der Messstelle, wenn "include=parameters" gesetzt wurde
          items:
            $ref: '#/components/schemas/Parameter'
        characteristics:
          type: array
          description: Optional eingebettete Kennwerte der Messstelle, wenn "include=characteristics" gesetzt wurde
          items:
            $ref: '#/components/schemas/Characteristic'
    SurfaceWaterStation:
      title: Pegel (Messstation Oberflächengewässer)
      description: |
        Pegel (Messstation Oberflächengewässer) - type: "surfaceWater"

        Messstation an Flüssen, Seen und anderen Oberflächengewässern.
      allOf:
      - $ref: '#/components/schemas/BaseStation'
      - type: object
        required:
        - waterBodyName
        properties:
          waterBodyId:
            type: string
            description: 'Gewässerkennzahl als eindeutige unveränderliche Id zur Verwendung in URLs. Vgl. https://de.wikipedia.org/wiki/Gewässerkennzahl_(Deutschland)#Wichtige_Gewässerkennzahlen'
            example: 242
          waterBodyName:
            type: string
            description: Name des Gewässers
            example: Regnitz
          riverHierarchy:
            type: string
            description: Gewässerfolge (Einordnung des Gewässers in das Flusssystem)
            example: Regnitz - Main - Rhein - Nordsee
          riverBasinID:
            type: string
            description: Gebietskennzahl des (meist übergeordneten) Flussgebiets
            example: 2
          riverBasinName:
            type: string
            description: Name des (meist übergeordneten) Flussgebiets
            example: Rhein
          catchmentAreaSize:
            type: object
            description: Einzugsgebietsgröße des Pegels (oberirdisch)
            properties:
              value:
                type: number
                description: Wert für die Einzugsgebietsgröße
                example: 555.3
              unit:
                type: string
                description: Einheit der Einzugsgebietsgröße entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: km2
              unitDisplay:
                type: string
                description: Benutzerfreundliche Anzeige der Einheit (km²)
                example: km²
          riverLocation:
            type: object
            description: Lage des Pegels am Gewässer
            properties:
              riverKilometre:
                type: number
                description: Flusskilometer (Stationierung)
                example: 426.2
              stationingOrigin:
                type: string
                description: >-
                  Bezugspunkt der Stationierung (`riverKilometre`): `source` = von der Quelle flussabwärts gezählt, `mouth` = von der Mündung flussaufwärts gezählt.
                enum:
                  - source
                  - mouth
                example: source
              distanceFromMouthKm:
                type: number
                description: Entfernung von der Mündung in Kilometern
                example: 32.6
              lateralPosition:
                type: string
                description: Lage am Gewässer (links, Mitte, rechts) in Fließrichtung gesehen
                enum:
                  - bank-left
                  - mid-stream
                  - bank-right
                example: bank-left
    GroundwaterStation:
      title: Grundwassermessstelle (Messstation Grundwasser)
      description: |
        Grundwassermessstelle (Messstation Grundwasser) - type: "groundwater"

        Messstation zur Erfassung von v.a. Grundwasserständen.
      allOf:
      - $ref: '#/components/schemas/BaseStation'
      - type: object
        properties:
          groundSurfaceElevation:
            type: object
            description: Höhe der Geländeoberkante
            properties:
              value:
                type: number
                description: Höhenwert der Geländeoberkante
                example: 445.18
              unit:
                type: string
                description: Einheit der Höhe der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
              unitDisplay:
                type: string
                description: Benutzerfreundliche Anzeige der Höhe der Geländeoberkante, ggf. mit Bezug zum Höhensystem
                example: m NHN
              epsgCode:
                type: integer
                description: EPSG-Code des Höhensystems. Standardwert ist DHHN 2016 (EPSG:7837).
                default: 7837
                example: 7837
          filterTopOfScreen:
            type: object
            description: Beginn des Filters unter der Geländeoberkante
            properties:
              value:
                type: number
                description: Relativer Wert für den Beginn des Filters unter der Geländeoberkante
                example: 12
              unit:
                type: string
                description: Einheit für den Beginn des Filters unter der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          filterBottomOfScreen:
            type: object
            description: Ende des Filters unter der Geländeoberkante
            properties:
              value:
                type: number
                description: Relativer Wert für das Ende des Filters unter der Geländeoberkante
                example: 13.95
              unit:
                type: string
                description: Einheit für das Ende des Filters unter der Geländeoberkante entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          aquifer:
            type: object
            description: Angabe zu den hydraulischen Druckverhältnissen
            properties:
              name:
                type: string
                description: Name Grundwasserkörper in dem die Messstelle verfiltert ist
                example: Panketalgrundwasserleiter (GWL 1.2)
              type:
                type: string
                description: Angabe zu den hydraulischen Druckverhältnissen
                example: ungespannt
          depthOfTheObservationWell:
            type: object
            description: Endtiefe der Grundwassermessstelle (relativ zur Geländeoberkante)
            properties:
              value:
                type: number
                description: Wert der Endtiefe der Grundwassermessstelle
                example: 10
              unit:
                type: string
                description: Einheit der Endtiefe der Grundwassermessstelle entsprechend der UCUM-Einheitencodes (https://units-of-measurement.org/)
                example: m
          subarea:
            type: object
            properties:
              id:
                type: integer
                description: Nummer des hydrogeologischen Teilraums oder des Einzugsgebiets
                example: 1315
              name:
                type: string
                description: Name des hydrogeologischen Teilraums oder des Einzugsgebiets
                example: Panketal
    MeteorologicalStation:
      title: Wetterstation (Messstation Meteorologie)
      description: |
        Wetterstation (Messstation Meteorologie) - type: "meteorological"
      allOf:
      - $ref: '#/components/schemas/BaseStation'
    Parameter:
      title: Parameter
      description: Informationen zur Messreihe und zur physikalischen Messgröße
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Eindeutige unveränderliche Id des Parameters zur Verwendung in URLs. Kann auch für die fachliche Identifikation des Parameters/Messreihe genutzt werden.
          example: water-level-rel-15min
        name:
          type: string
          description: Name/Bezeichnung des Parameter
          example: Wasserstand , relativ
        description:
          type: string
          description: Ausführliche Beschreibung des Parameters und seiner Bedeutung
          example: Relativer Wasserstand in Zentimetern
        interval:
          type: string
          format: duration
          description: "Zeitlicher Abstand zwischen aufeinanderfolgenden Messungen bzw. Datenpunkten als ISO-8601 'duration' (z.B. 'PT15M' bedeutet alle 15 Minuten wird ein Wert erfasst)."
          example: PT15M
        availability:
          type: array
          description: Zeitspannen, in denen Daten verfügbar sind
          items:
            type: object
            required:
            - start
            - end
            properties:
              start:
                type: string
                format: date-time
                description: Beginn der Datenverfügbarkeit
              end:
                type: string
                format: date-time
                description: Ende der Datenverfügbarkeit
        observedProperty:
          type: string
          description: Die physikalische Eigenschaft, die gemessen wird
          enum:
          - water-level-rel
          - water-level-abs
          - discharge
          - water-temperature
          - flow-rate
          - precipitation
          - snow-depth
          - snow-water-equivalent
          - air-temperature
          - dew-point
          - relative-humidity
          - wind-speed
          - wind-direction
          - solar-radiation
          - sunshine-duration
          - air-pressure
          - groundwater-level-rel
          - groundwater-level-abs
          - groundwater-temperature
          - spring-discharge
        unit:
          type: string
          description: Standardisierte ASCII UCUM-Einheitencodes (Unified Code for Units of Measure). Siehe https://units-of-measurement.org/
          enum:
          - cm
          - m
          - m3/s
          - Cel
          - m/s
          - mm
          - '%'
          - deg
          - W/m2
          - min
          - hPa
          - L/s
          example: cm
        unitDisplay:
          type: string
          description: Benutzerfreundliche Anzeige der Einheit (m³/s, °C, usw.)
          example: m³/s
        procedure:
          type: string
          description: Verfahren zur Werterzeugung
          enum:
          - measured
          - manual
          - calculated
          - simulated
          - predicted
        aggregationType:
          type: string
          description: "Art der Aggregation der Messwerte. 'instantaneous' für Momentanwerte zu einem bestimmten Zeitpunkt, 'average' für Mittelwerte über einen Zeitraum, 'maximum' und 'minimum' für Extremwerte innerhalb eines Zeitraums, 'cumulative' für aufsummierte Werte (z.B. Niederschlagssummen)"
          enum:
          - instantaneous
          - average
          - maximum
          - minimum
          - cumulative
        aggregationDuration:
          type: string
          format: duration
          description: "Zeitraum über den die Messwerte aggregiert werden (z.B. 'PT15M' bedeutet Mittelwert über 15 Minuten). Wird nur bei aggregierten Messungen (mean, maximum, minimum, cumulative) verwendet. Nicht zu verwechseln mit 'interval', welches den Abstand zwischen aufeinanderfolgenden Messungen definiert."
          example: PT15M
        status:
          $ref: '#/components/schemas/OperationalStatus'
        values:
          type: array
          description: Optionale eingebettete Werte, wenn "include=values" gesetzt wurde
          items:
            $ref: '#/components/schemas/Value'
    Value:
      title: Wert mit Zeitstempel
      description: Wert mit Zeitstempel und optionalen Flags
      type: object
      required:
      - timestamp
      - value
      properties:
        timestamp:
          type: string
          format: date-time
          description: Datums- Zeitstempel des Wertes im ISO 8601 Format mit Zeitzone
          example: '2025-01-27T12:00:00+01:00'
        value:
          type: number
          nullable: true
          description: Der numerische Messwert
          example: 287
        quality:
          type: string
          description: Optionale Flags (z.B. Qualitätseinstufungen) für den Messwert
          enum:
          - good
          - suspect
          - estimate
          - poor
          - unchecked
          - missing
          example: good
    Forecast:
      title: Vorhersage mit Zeitstempel
      description: Vorhersage mit Zeitstempel, Berechnungszeitpunkt und optionalen Flags. Kann entweder einen einzelnen Wert oder mehrere Perzentil-Werte (probabilistisch) enthalten.
      type: object
      required:
      - initialized
      - timestamp
      properties:
        initialized:
          type: string
          format: date-time
          description: Zeitpunkt zu dem die Vorhersage erstellt bzw. errechnet wurde im ISO 8601 Format mit Zeitzone
          example: '2025-01-27T06:00:00+01:00'
        timestamp:
          type: string
          format: date-time
          description: Datums-Zeitstempel der Vorhersage im ISO 8601 Format
          example: '2025-01-27T12:00:00+01:00'
        value:
          type: number
          nullable: true
          description: Der numerische Vorhersagewert für Einzel-Vorhersagen
          example: 287
        quality:
          type: string
          description: Optionale Flags (z.B. Genauigkeitsangaben) für die Vorhersage
          enum:
          - low
          - medium
          - high
          example: high
        percentiles:
          type: array
          description: Array von Perzentil-Vorhersagen für probabilistische Vorhersagen.
          items:
            type: object
            required:
            - percentile
            - value
            properties:
              percentile:
                type: number
                minimum: 0
                maximum: 100
                description: Perzentil-Wert (0-100). Z.B. 10 für das 10%-Perzentil, 50 für den Median, 90 für das 90%-Perzentil.
                example: 50
              value:
                type: number
                description: Vorhersagewert für dieses Perzentil
                example: 295
    ValueArray:
      title: Kompakte Werteliste
      description: >-
        Kompakte Darstellung einer äquidistanten Zeitreihe als Array von Zahlenwerten. Die Zeitstempel ergeben sich implizit aus dem Startzeitpunkt (`from`) und dem Messintervall (`interval`). Fehlende Werte werden als `null` dargestellt. Dieses Format eignet sich für kontinuierliche Zeitreihen mit konstantem Intervall und reduziert die Datenmenge (komprimiert und unkomprimiert) erheblich gegenüber der Standarddarstellung.
      type: object
      required:
      - from
      - interval
      - values
      properties:
        from:
          type: string
          format: date-time
          description: Startzeitpunkt der Zeitreihe (ISO 8601 mit Zeitzone), entspricht dem Zeitstempel des ersten Werts
          example: '2025-01-27T00:00:00+01:00'
        interval:
          type: string
          format: duration
          description: "Zeitlicher Abstand zwischen aufeinanderfolgenden Werten als ISO-8601 Duration (z.B. 'PT15M' für 15-Minuten-Werte)"
          example: PT15M
        values:
          type: array
          description: >-
            Array von Messwerten in zeitlicher Reihenfolge. Der erste Wert entspricht dem Zeitpunkt `from`, jeder folgende Wert liegt um `interval` später. `null` kennzeichnet fehlende Werte.
          items:
            type: number
            nullable: true
          example: [ 287, 289, null, 291, 293, 295 ]
    Characteristic:
      title: Kennwert
      description: Kennwert mit Informationen zu statistischen Maßzahlen, abgeleiteten Werten, gewässerkundlichen Hauptwerten oder Wasserstandsmarken
      type: object
      required:
      - id
      - value
      properties:
        id:
          type: string
          description: 'Eindeutige unveränderliche Id des Kennwerts zur Verwendung in URLs. Kann auch für die fachliche Identifikation der Kenngröße genutzt werden. Beispiele: discharge-mean-summer, water-level-rel-min-known, water-level-rel-max'
          example: discharge-mean-summer
        shortname:
          type: string
          description: 'Kurzbezeichnung des Kennwerts nach DIN 4049-3. Beispiele: MQ(5,10), NNW, HW'
          example: MQ(5,10)
        name:
          type: string
          description: Name/Bezeichnung des Kennwerts
          example: Mittlerer Abfluss, Sommerhalbjahr
        description:
          type: string
          description: Ausführliche Beschreibung des Kennwerts und sein zeitlicher Bezug
          example: Arithmetischer Mittelwert des täglichen Abflusses im hydrologischen Sonnenhalbjahr (Mai-Okt.)
        period:
          type: string
          description: Optionale wiederkehrende Zeitspanne, auf die sich der Kennwert bezieht. Z.B. hydrologisches Jahr, hydrologisches Halbjahr, bestimmte Monate usw.
          example: '--05-01/--10-30'
        referencePeriod:
          type: string
          description: "Zeitraum i. d. R. in Jahren, der die Datengrundlage für den Kennwert darstellt, als ISO-8601 'time interval'"
          example: 1991/2020
        validFrom:
          type: string
          format: date-time
          description: "Zeitpunkt ab dem z.B. eine Wasserstandsmarke gültig ist"
          example: 2023-01-01
        occurredAt:
          type: string
          format: date-time
          description: "Zeitpunkt zu dem ein bestimmtes Ereignis aufgetreten ist. Also zum Beispiel wann wurde ein Höchstwasserstand gemessen."
          example: 2013-06-02
        observedProperty:
          type: string
          description: Die physikalische Eigenschaft, die gemessen wird
          enum:
          - water-level-rel
          - water-level-abs
          - discharge
          - water-temperature
          - flow-rate
          - precipitation
          - snow-depth
          - snow-water-equivalent
          - air-temperature
          - dew-point
          - relative-humidity
          - wind-speed
          - wind-direction
          - solar-radiation
          - sunshine-duration
          - air-pressure
          - groundwater-level-rel
          - groundwater-level-abs
          - groundwater-temperature
          - spring-discharge
        unit:
          type: string
          description: Standardisierte ASCII UCUM-Einheitencodes (Unified Code for Units of Measure). Siehe https://units-of-measurement.org/
          enum:
          - cm
          - m
          - m3/s
          - Cel
          - m/s
          - mm
          - '%'
          - deg
          - W/m2
          - min
          - hPa
          - L/s
          example: cm
        unitDisplay:
          type: string
          description: Benutzerfreundliche Anzeige der Einheit (m³/s, °C, usw.)
          example: m³/s
        value:
          type: number
          description: Numerischer Wert des Kennwerts
          example: 870
    Error:
      description: Standardisierte Fehlerantwort mit Meta-Informationen
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        data:
          type: object
          description: Detaillierte Fehlerinformationen
          required:
          - code
          - message
          properties:
            status:
              type: integer
              description: Optionaler HTTP-Statuscode des Fehlers
              example: 404
            code:
              type: string
              description: Fehlercode zur Identifikation des Fehlertyps
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              description: Menschenlesbare Fehlermeldung
              example: Die angeforderte Ressource existiert nicht
            details:
              type: array
              description: Optionale zusätzliche Details zum Fehler, z.B. Fehler bei einzelnen Query-Parametern
              items:
                type: string
              example:
              - Station mit ID 'xyz' wurde nicht gefunden
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication mit Username und Passwort. Geeignet für einfache interne Systeme und Legacy-Integration. Muss zwingend über HTTPS verwendet werden.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 oder JWT Token für sichere, tokenbasierte Authentifizierung. Geeignet für moderne Anwendungen mit Benutzer-Login und fein-granularen Berechtigungen. Header-Format: Authorization: Bearer <token>
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API-Schlüssel für Zugriffskontrolle und Nutzungsstatistik. Geeignet für Server-zu-Server-Kommunikation und bekannte Partner. Header-Format: X-API-Key: <schlüssel>
  headers:
    CacheControlHeader:
      description: >-
        Optionale Angaben zur Cachebarkeit des Responses. Insbesondere über `max-age` kann bestimmt werden wie lange die Ressource aktuell ist, also wie lang der Client gänzlich auf eine Anfrage verzichten kann.
      required: false
      schema:
        type: string
      example: 'max-age=3600, public'
    ETagHeader:
      description: >-
        Optionaler Hashwert, der eine spezifische Version der Ressource/Response identifiziert. Der Hashwert ändert sich erst bei Veränderung des Response. Der Client kann dann eine bedingte Anfrage per 'If-None-Match` Request-Header machen. Hat sich nichts geändert, so kann der Server ein 304 "Not Modified" ohne Response zurückgeben, um unnötige Datenübertragungen zu vermeiden.
      required: false
      schema:
        type: string
      example: '"1234567890abcdef"'
  responses:
    BadRequest:
      description: "400 Bad Request - Die Anfrage ist fehlerhaft oder ungültig. Ein allgemeiner Fehler, wenn der Server die Anfrage aufgrund eines Client-Fehlers nicht verarbeiten kann."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 400
              code: BAD_REQUEST
              message: Die Anfrage ist fehlerhaft oder ungültig
              details:
              - Der Parameter 'from' hat ein ungültiges Datumsformat
    Unauthorized:
      description: "401 Unauthorized - Authentifizierung ist erforderlich, fehlt aber oder ist ungültig. Der Client muss sich authentifizieren, um auf die Ressource zuzugreifen."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 401
              code: UNAUTHORIZED
              message: Authentifizierung ist erforderlich
              details:
              - Der API-Schlüssel ist ungültig oder fehlt
    Forbidden:
      description: "403 Forbidden - Der Client ist authentifiziert, hat aber keine Berechtigung für diese Ressource."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 403
              code: FORBIDDEN
              message: Zugriff auf diese Ressource ist nicht erlaubt
              details:
              - Sie haben keine Berechtigung, auf diese Station zuzugreifen
    NotFound:
      description: "404 Not Found - Die angeforderte Ressource existiert nicht. Einer der häufigsten Statuscodes."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 404
              code: NOT_FOUND
              message: Die angeforderte Ressource existiert nicht
              details:
              - Station mit der ID 'a0af41ce-1899-4192-bc70-2fe66581bc8b' wurde nicht gefunden
    TooManyRequests:
      description: "429 Too Many Requests - Der Client hat zu viele Anfragen in einem bestimmten Zeitraum gesendet (Rate-Limiting)."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 429
              code: TOO_MANY_REQUESTS
              message: Zu viele Anfragen
              details:
              - Die maximale Anzahl von 100 Anfragen pro Minute wurde überschritten
    InternalServerError:
      description: "500 Internal Server Error - Ein allgemeiner Serverfehler ist aufgetreten. Der Server hat eine unerwartete Bedingung angetroffen."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 500
              code: INTERNAL_SERVER_ERROR
              message: Ein interner Serverfehler ist aufgetreten
              details:
              - Bitte versuchen Sie es später erneut
    ServiceUnavailable:
      description: "503 Service Unavailable - Der Server ist vorübergehend nicht in der Lage, die Anfrage zu bearbeiten, oft aufgrund von Wartungsarbeiten oder Überlastung."
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            meta:
              title: Projekt HydroDaten API
              version: 1.0.0
              publisherName: Hochwasservorhersagezentrale
              licenseName: CC BY 4.0
              licenseUrl: https://creativecommons.org/licenses/by/4.0/deed.de
            data:
              status: 503
              code: SERVICE_UNAVAILABLE
              message: Der Service ist vorübergehend nicht verfügbar
              details:
              - Wartungsarbeiten werden durchgeführt. Bitte versuchen Sie es in 30 Minuten erneut
    MovedPermanently:
      description: "301 Moved Permanently - Die Ressource wurde dauerhaft verschoben. Der Client sollte zukünftige Anfragen an die neue URI richten."
      headers:
        Location:
          description: Neue URI der verschobenen Ressource
          required: true
          schema:
            type: string
            format: uri
          example: https://api.hydrodaten.de/v2/stations/a0af41ce-1899-4192-bc70-2fe66581bc8b
    NotModified:
      description: "304 Not Modified - Die Ressource wurde seit der letzten Anfrage nicht verändert. Wird als Antwort auf If-Modified-Since oder If-None-Match Anfragen zurückgegeben, um unnötige Datenübertragungen zu vermeiden."
  parameters:
    AcceptHeader:
      name: Accept
      in: header
      required: false
      description: >-
        Gewünschtes Antwortformat via HTTP Content Negotiation (RESTful Standard). Der format Query-Parameter hat Vorrang, falls beide angegeben sind.
      schema:
        type: string
        enum:
        - application/json
        - text/csv
        - application/xml
        - application/geo+json
        default: application/json
      example: 'application/json'
    AcceptEncodingHeader:
      name: Accept-Encoding
      in: header
      required: false
      description: >-
        Der Client teilt dem Server mit, dass er die Antwort in komprimierter Form (gzip) senden kann. Insbesondere bei JSON-Responses sehr effektiv.
      schema:
        type: string
      example: 'gzip, deflate'
    IfNoneMatchHeader:
      name: If-None-Match
      in: header
      required: false
      description: >-
        Der Header wird für bedingte Anfragen verwendet und enthält ETag-Werte, mit denen der Server prüft, ob sich eine Ressource geändert hat. Stimmen die ETags überein, antwortet der Server mit Status 304 "Not Modified", um unnötige Datenübertragungen zu vermeiden.
      schema:
        type: string
      example: '"1234567890abcdef"'
    FormatParameter:
      name: format
      in: query
      required: false
      description: >-
        Gewünschtes Ausgabeformat für die Response. Dieser Parameter überschreibt den Accept-Header, falls beide angegeben sind. Ermöglicht einfaches Testen und Teilen von formatierten URLs. Standard ist JSON, wenn weder format-Parameter noch Accept-Header angegeben sind.
      schema:
        type: string
        enum:
        - application/json
        - text/csv
        - application/xml
        - application/geo+json
        default: application/json
      example: application/json
    FieldsParameter:
      name: fields
      in: query
      required: false
      description: >-
        Ermöglicht die Auswahl spezifischer Felder in der Antwort (Sparse Fieldsets). Reduziert die Datenmenge und verbessert die Performance, indem nur angeforderte Felder zurückgegeben werden.


        **Syntax:**

        Kommagetrennte Liste von Feldnamen mit Punkt-Notation für verschachtelte Strukturen:

        - Format: `fields=feld1,feld2,objekt.eigenschaft`

        - Beispiel: `?fields=id,name,coordinates.lat,coordinates.lon`


        **Punkt-Notation für verschachtelte Strukturen:**

        Die Punkt-Notation funktioniert einheitlich für:

        - **Verschachtelte Objekte** (z.B. `coordinates.lat` für das `lat`-Feld im `coordinates`-Objekt)

        - **Eingebettete Ressourcen** (z.B. `parameters.id` für das `id`-Feld in eingebetteten `parameters`)


        **Verhalten:**

        - Nur die Felder im `data`-Abschnitt werden gefiltert

        - Die Abschnitte `meta` und `links` werden immer vollständig zurückgegeben

        - Ungültige Feldnamen werden ignoriert

        - Bei Verwendung mit `include`: Eingebettete Ressourcen können ebenfalls gefiltert werden


        **Beispiele:**


        **Einfache Feldauswahl:**

        - `?fields=id,name` - Nur ID und Name der Hauptressource

        - `?fields=id,name,coordinates.lat,coordinates.lon` - ID, Name und nur Koordinaten aus coordinates


        **Eingebettete Ressourcen filtern (mit include-Parameter):**

        - `?include=parameters&fields=id,name,parameters.id,parameters.name,parameters.unit` -
          Station auf id/name filtern, eingebettete Parameter auf id/name/unit filtern
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
    SortParameter:
      name: sort
      in: query
      required: false
      description: >-
        Sortierung der Ergebnisse nach einem oder mehreren Feldern.


        **Format:**

        - Aufsteigend: Feldname ohne Präfix (z.B. `sort=name`)

        - Absteigend: Feldname mit Minus-Präfix (z.B. `sort=-name`)

        - Mehrere Felder: Kommagetrennt (z.B. `sort=state,-name`)


        **Verhalten:**

        - Mehrere Sortierungen werden in der angegebenen Reihenfolge angewendet

        - Ungültige Feldnamen werden ignoriert

        - Standard-Sortierung wenn Parameter fehlt: implementierungsabhängig (typischerweise nach ID)


        **Sortierbare Felder variieren je nach Endpunkt:**

        - Stationen: `id`, `name`, `water`, `operator`, `state`

        - Parameter: `id`, `name`, `unit`, `observedProperty`

        - Kennwerte: `id`, `name`, `value`, `occurredAt`

        - Werte: `timestamp`, `value`


        **Beispiele:**

        - `?sort=name` - Nach Name aufsteigend sortieren

        - `?sort=-name` - Nach Name absteigend sortieren

        - `?sort=state,-name` - Erst nach Bundesland aufsteigend, dann nach Name absteigend
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
tags:
- name: API-Metadaten
  description: >-
    API-Root, Service-Discovery, Metadaten und Health-Endpoint
- name: Stationen
  description: >-
    Messstationen wie Oberflächengewässermessstationen, Grundwassermessstationen oder meteorologische Messstationen
- name: Parameter
  description: >-
    An einer Messstation verfügbare Messparameter (z.B. Wasserstand, Abfluss, Lufttemperatur) inklusive Einheit und Messintervall.
- name: Werte
  description: >-
    Messwerte (z.B. Wasserstände, Abflüsse, Temperaturen) mit Zeitstempeln und optionalen Qualitäts-Flags
- name: Kennwerte
  description: >-
    Statistische Kennwerte und abgeleitete Maßzahlen (z.B. Mittelwerte, Schwellenwerte, Extremwerte) für Messstationen
security:
- {}
- BasicAuth: []
- BearerAuth: []
- ApiKeyAuth: []
