Designing Data Contracts / Datenverträge entwerfen

Datenverträge entwerfen

Wann einsetzen

• Ein vorgelagertes System (Service, Ereignis, API, Datei) speist nachgelagerte Pipelines und eine Änderung könnte diese still brechen.
• Definieren der Schnittstelle zwischen einem produzierenden Team/System und dem Data Warehouse.
• Hinzufügen von Schema-/Qualitätsdurchsetzung an der Importgrenze.
• NICHT verwenden für interne Modell-zu-Modell-Änderungen innerhalb eines einzelnen dbt-Projekts (verwende Tests + handling-schema-evolution).

Was ein Vertrag spezifiziert

• Schema: Felder, Typen, Nullability und zulässige Werte.
• Semantik: Was jedes Feld bedeutet, seine Einheit und Körnung.
• Garantien: Frische/SLA, Volumenerwartungen, Eindeutigkeit von Schlüsseln.
• Verantwortlichkeiten: Wer produziert und wen man kontaktieren kann.
• Versionierung + Änderungsrichtlinie: Wie breaking changes kommuniziert werden.

Workflow

- [ ] Vertrag als versioniertes, eingechecktes Schema schreiben (kein implizites Wissen)
- [ ] An der Importgrenze durchsetzen (bei Ankunft validieren)
- [ ] Änderungen klassifizieren: additiv (sicher) vs. breaking (erfordert neue Version)
- [ ] Bei Verstoß ablehnen/quarantänisieren und den Produzenten alarmieren
- [ ] Breaking changes rechtzeitig versionieren und kommunizieren

1. Explizit und versioniert machen. Den Vertrag als Code speichern (JSON Schema, Avro/Protobuf-Schema oder eine YAML-Spezifikation) neben der Pipeline, wie jede API reviewed.
2. An der Grenze durchsetzen. Eingehende Daten bei Ankunft gegen den Vertrag validieren; Verstöße ablehnen oder quarantänisieren statt sie zu laden.
3. Änderungen klassifizieren. Additive/optionale Felder = rückwärtskompatibel. Felder entfernen, umbenennen, Typen/Nullability verschärfen = breaking → neue Version.
4. Laut beim Produzenten scheitern, nicht still downstream.

Muster

Vertrag als JSON Schema (bei Import durchgesetzt):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["order_id", "amount", "ordered_at"],
  "properties": {
    "order_id": { "type": "string" },
    "amount": { "type": "number", "minimum": 0 },
    "ordered_at": { "type": "string", "format": "date-time" },
    "coupon": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Durchsetzungspunkt – jeden Datensatz beim Import validieren; Fehler in einen Quarantänebereich leiten, mit Grund versehen und das produzierende Team alarmieren. Dies verwandelt ein stilles nachgelagertes Scheitern in ein sofortiges, owned Signal an der Quelle.

Schema Registry (Kafka/Avro) – Kompatibilität (BACKWARD) zum Zeitpunkt der Veröffentlichung durchsetzen, sodass Produzenten kein inkompatibles Schema ausliefern können.

Häufige Fallstricke

• Vertrag nur als Dokumentation – wenn er nicht im Code durchgesetzt wird, driftet er ab und bricht still.
• Durchsetzung tief im Warehouse – Verstöße an der Grenze abfangen, bevor sich schlechte Daten ausbreiten.
• Keine Versionierung – jede Änderung wird zum Notfall; versioniere und deaktiviere elegant.
• additionalProperties uneingeschränkt wenn Strenge benötigt wird – unerwartete Felder schlüpfen durch; setze es auf false, wo angemessen.
• Kein Besitzer – ein abgelehnter Batch ohne Ansprechpartner blockiert die Pipeline.
• Breaking changes ohne Vorlaufzeit – Produzent/Konsument über versionierte Schemas und ein Deprecation-Fenster koordinieren.