8 · Querschnittliche Konzepte¶
Querschnittliche Konzepte sind Lösungsansätze, die in mehreren Stacks und Diensten der ODI gleich umgesetzt sind. Sie regeln, wie alle Bausteine mit gemeinsamen Problemen umgehen: Wer darf was? Welche Datenformate werden erzeugt? Wie werden Fehler behandelt?
Identität und Authentifizierung¶
Alle schreibenden Endpunkte der ODI erfordern ein gültiges JWT, das von Keycloak ausgestellt wurde. Keycloak läuft als eigene Instanz im ODI-Cluster (Namespace keycloak, Realm open-data-infrastruktur) und ist per Federated Identity an den Dataport Identity Provider angebunden. Verwaltungsmitarbeitende melden sich damit über ihren bestehenden Dataport-Account an, ohne ein separates ODI-Konto zu benötigen.
Für den programmatischen Zugriff (Fachverfahren, Skripte) gilt der OAuth-2.0-Client-Credentials-Flow: Ein Service Account erhält client_id und client_secret und tauscht diese gegen ein kurzlebiges JWT ein. Dienste prüfen die JWT-Signatur lokal gegen den öffentlichen Schlüssel von Keycloak – ein zweiter Netzwerkaufruf pro Request ist nicht nötig.
Keycloak-Endpunkte:
- Produktion:
https://keycloak.odi.schleswig-holstein.de - Stage:
https://keycloak.odi-stage.schleswig-holstein.de - Realm:
open-data-infrastruktur
Autorisierung: Permissions statt Rollen¶
Die ODI verwendet feingranulare Berechtigungs-Claims im JWT statt grober Rollen wie „Admin" oder „Editor". Ein JWT-Claim kann zum Beispiel das Recht enthalten, Datensätze in einem bestimmten Katalog zu veröffentlichen, Schemas anzulegen oder Publisher zu verwalten – ohne dabei andere Operationen zu erlauben.
Dieses Modell macht Zugriffsrechte transparent: Wer wissen möchte, was ein Client darf, liest seine JWT-Claims, ohne eine Rollentabelle zu konsultieren. Es erleichtert auch die Fehlersuche, da unerlaubte Zugriffe direkt auf fehlende Claims zurückgeführt werden können.
Datenformate und Repräsentationen¶
Ein einmal hochgeladener Datensatz liegt im Datenkatalog in mehreren Formaten vor. Jedes Format bedient ein konkretes Nutzungsszenario.
Das Diagramm zeigt, wie aus einer eingehenden CSV-Datei mehrere Repräsentationen entstehen, die jeweils unterschiedlichen Zielgruppen dienen.
| Repräsentation | Format | Zweck |
|---|---|---|
| CSV (Original) | .csv |
Unveränderte Ausgangsdatei; Download für Datenbereitsteller und -nutzer |
| Tabular Data Resource (TDR) | JSON (Frictionless) | Formale, maschinenlesbare Beschreibung der Tabellenstruktur inkl. Schema |
| Parquet | .parquet |
Spaltenorientiertes Format; effizient für analytische Abfragen mit Spark, DuckDB o. Ä. |
| JSON | .json |
Zeilenbasierte programmatische Weiterverarbeitung |
| RDF | Turtle / JSON-LD | Linked-Open-Data-Repräsentation; abfragbar über den SPARQL-Endpunkt (Apache Jena Fuseki) |
| GeoJSON | .geojson |
Nur wenn das Schema Geo-Felder enthält; Grundlage für WFS-Dienst und Masterportal-Karte |
| GeoParquet | .geoparquet |
Geodaten im Parquet-Format für analytische GIS-Workloads |
| WFS / WMS | OGC-Dienste | Vektordaten (WFS) und gerenderte Kacheln (WMS) über GeoServer bereitgestellt |
Die Konvertierung übernehmen das odi-frictionless-backend (CSV → Parquet, JSON, TDR), der triple-converter-worker (→ RDF) und das Staging-Backend mithilfe von ogr2ogr (→ GeoJSON, GeoParquet).
Fehlerbehandlung¶
Die Dienste der ODI unterscheiden zwei Fehlerklassen, die unterschiedlich behandelt werden:
Fachliche Fehler entstehen aus dem Inhalt oder dem Kontext der Anfrage: ungültiges JWT, fehlende Berechtigung, unbekannte Schema-ID, CSV mit Typfehlern, fehlendes Pflichtfeld in den Metadaten. Diese Fehler werden früh erkannt – noch bevor irgendein Datensatz im Katalog angelegt wird – und als strukturierte Fehlerliste an den Aufrufer zurückgegeben (HTTP 4xx). Es entsteht kein unvollständiger Systemzustand.
Technische Fehler entstehen aus der Infrastruktur: ein Dienst ist nicht erreichbar, der Objektspeicher antwortet nicht, die Datenbankverbindung schlägt fehl. Diese Fehler werden geloggt (Loki) und lösen HTTP 5xx aus. Sie veranlassen den Aufrufer zum Retry; idempotente Endpunkte (z. B. PUT /upload/csv/overwrite/{datasetId}) sind so gestaltet, dass ein Retry keinen Duplikat-Datensatz erzeugt.
Eine Ausnahme bildet der optionale Geodaten-Zweig: Tritt dort nach erfolgreicher Kataloganlage ein Fehler auf (z. B. GeoServer nicht erreichbar), wird der Fehler protokolliert und der Upload insgesamt als erfolgreich betrachtet. Der Datensatz ohne Geo-Aufbereitung ist besser als gar kein Datensatz.
Hexagonale Architektur¶
Innerhalb der einzelnen Dienste – besonders im odi-staging-backend – ist die Fachlogik von den technischen Adaptern getrennt. Der Fachkern (Domain) kennt keine konkreten HTTP-Bibliotheken, keine Datenbankverbindungen und keine externen API-Details. Er arbeitet mit Interfaces (Ports), die von Adaptern implementiert werden.
Das greifbarste Beispiel ist der odi-ckan-service: Das Staging-Backend ruft nicht direkt das CKAN-API auf, sondern einen Adapter, der den CKAN-Service anspricht. Soll der Datenkatalog von CKAN auf Piveau umgestellt werden, ist nur der Adapter (der CKAN-Service selbst) auszutauschen – die Fachlogik des Staging-Backends bleibt unverändert. Dieses Muster beschreibt Kapitel 9 (ADR-1) als explizite Architekturentscheidung.
Konfiguration und Umgebungsvariablen¶
Alle Dienste der ODI folgen dem 12-Factor-Prinzip für Konfiguration: Kein Konfigurationswert ist im Code hinterlegt. Hostnamen, Ports, Keycloak-URL und -Realm, Datenbank-Verbindungsstrings, S3-Endpunkte und API-Keys kommen ausschließlich aus Umgebungsvariablen.
In Kubernetes werden diese Werte als ConfigMaps (nicht-sensible Konfiguration) und Secrets (Passwörter, Tokens) bereitgestellt. Die Trennung zwischen Stage und Produktion ergibt sich damit allein aus unterschiedlichen Umgebungsvariablen – der Code aller Dienste ist identisch.
Für lokale Entwicklung übernimmt Docker Compose (odi-docker-compose-deployment) die Konfigurationsübergabe per .env-Datei.