# Data Model

Die API nutzt eine einheitliche Response-Struktur. Dadurch können Partner:innen Endpunkte konsistent integrieren.

## Erfolgreiche Response

```json
{
  "meta": {
    "apiVersion": "v1",
    "generatedAt": "2026-08-18T15:00:00+02:00",
    "source": "lenzerheide_data_layer",
    "visibility": "partner",
    "module": "traffic"
  },
  "data": {}
}
```

## `meta`

| Feld | Typ | Beschreibung |
|---|---|---|
| `apiVersion` | string | API-Version, z. B. `v1` |
| `generatedAt` | datetime | Zeitpunkt der Antwortgenerierung |
| `source` | string | Datenquelle / Systemkontext |
| `visibility` | string | `public` oder `partner` |
| `module` | string | API-Modul, z. B. `traffic`, `weather` oder `lifts` |

## `data`

`data` enthält die fachlichen Daten des Endpunkts.

Die konkrete Struktur ist pro Endpunkt in Swagger dokumentiert:

```txt
https://docs.lenzerheide.swiss
```

## Fehlerantwort

Bestehende `/v1`-Endpunkte liefern bei Fehlern **kein** `meta`-Objekt. Die Legacy-Fehlerstruktur bleibt fuer die V1-Kompatibilitaet unveraendert:

```json
{
  "error": {
    "code": "MISSING_SCOPE",
    "message": "Missing required scope.",
    "details": {}
  }
}
```

## `error`

| Feld | Typ | Beschreibung |
|---|---|---|
| `code` | string | maschinenlesbarer Fehlercode |
| `message` | string | kurze Fehlermeldung |
| `details` | object | strukturierte Zusatzinformationen (gegebenenfalls leer) |

## Zeitformat

ISO-8601 wird für echte DateTime-Felder verwendet.

Beispiel:

```txt
2026-08-18T15:00:00+02:00
```

Für Weather gilt zusätzlich eine klare Zeitsemantik:

| Feld | Bedeutung |
|---|---|
| `sourceCreatedAt` | Source-Referenz des MeteoSwiss Forecasts im Format `YYYYMMDDHHMM` |
| `capturedAt` | Zeitpunkt der Erfassung/Aktualisierung im Data Layer |
| `observedAt` | Legacy-Alias für `capturedAt`; bei Weather keine Stationsmesszeit |
| `updatedAt` | letzter Update-Zeitpunkt des kanonischen Data-Layer-Datensatzes |

`observedAt` bleibt innerhalb von `/v1` aus Kompatibilitätsgründen erhalten, ist für Weather aber als Legacy-Feld dokumentiert. Neue Integrationen sollen `capturedAt` und `sourceCreatedAt` verwenden.

## Datumsformat

Query-Parameter für Datum verwenden:

```txt
YYYY-MM-DD
```

Beispiel:

```txt
2026-08-18
```

## Wetter-Semantik

Das Weather Data Product unterscheidet explizit zwischen Forecast und Beobachtung:

```txt
dataType = forecast | observation | unknown
isForecast = true | false | null
```

Seit 18. August 2026 ist MeteoSwiss OGD Local Forecast für Punkt `707800` / Lenzerheide/Lai die produktive Weather Source of Truth. Die Public- und Partner-Tageswerte sind deshalb im Normalbetrieb Forecast-Werte und keine Echtzeit-Stationsmessungen.

Nicht vom aktuellen MeteoSwiss Daily Forecast gelieferte Legacy-Felder bleiben `null`. Fehlende Werte werden nicht aus anderen Quellen verdeckt ergänzt.

## Standortschlüssel

Wetter-Endpunkte unterstützen den Parameter:

```txt
location_key
```

Wenn kein Wert mitgegeben wird, verwendet der Data Layer den serverseitig konfigurierten Standardstandort. Der aktuell dokumentierte und produktiv verwendete Standard ist:

```txt
lenzerheide
```

Die API validiert die Syntax des Schlüssels. Weitere Standortschlüssel werden deshalb erst als unterstützt dokumentiert, wenn sie fachlich freigegeben und produktiv verifiziert sind.

## Interoperabilitätsprofil

Der Data Layer verwendet für den kanonischen API-Austausch die W.O.W. Interoperability Foundation `0.1.0`.

Verbindlich für neue cross-repo Verträge:

- JSON und OpenAPI 3.x; die bestehenden APIs bleiben auf OpenAPI 3.0.3 kompatibel.
- Echte DateTime-Werte sind RFC3339/ISO-8601 mit Zeitzoneninformation.
- Datumswerte verwenden `YYYY-MM-DD`.
- Kanonischer GeoJSON-Austausch verwendet RFC 7946 / WGS84 / EPSG:4326 in Longitude-Latitude-Reihenfolge.
- Sprachen verwenden BCP 47, Länder ISO 3166-1 alpha-2, Währungen ISO 4217 alpha-3.
- Neue maschinenlesbare Einheiten verwenden UCUM oder eine explizit versionierte Domain-Zuordnung.
- schema.org/JSON-LD ist eine externe Mapping-/Publikationsschicht und kein internes Datenbankmodell.

Bestehende `/v1`-Verträge werden nicht stillschweigend umgedeutet. Zwei Kompatibilitätsausnahmen sind in `foundation/interoperability/profile.json` versioniert: MeteoSwiss `sourceCreatedAt` bleibt die source-native `YYYYMMDDHHMM`-Referenz, und bestehende KPI-/API-Unit-Codes bleiben bis zu einer versionierten Migration stabil.

Die Foundation-Adoption erteilt keine Public-, Partner-, Open-Data- oder AI-Freigabe. Diese bleiben eigenständige Purpose-, Rights-, Privacy-, Quality- und Security-Gates.

## Kompatibilität

Innerhalb von `/v1` können neue Felder ergänzt werden. Integrationen sollten unbekannte Felder ignorieren können.

Breaking Changes werden nicht stillschweigend innerhalb von `/v1` eingeführt.