Data Contract

Wenn Du jemandem einen Brief schickst, erwartest Du, dass der Empfänger ihn lesen kann. Ein Data Contract ist wie eine Vereinbarung über die "Sprache" von Daten - er stellt sicher, dass alle Beteiligten die gleichen Informationen gleich verstehen.

Das Problem ohne Vereinbarung

Systeme tauschen ständig Daten aus. Aber was bedeutet "Preis"? Ist das in Euro oder Cent? Mit oder ohne Mehrwertsteuer? Als Ganzzahl oder Dezimalzahl? Ohne klare Definition entstehen subtile Fehler, die oft erst beim Kunden sichtbar werden.

Die Lösung: Der Data Contract

Ein Data Contract definiert präzise:

Welche Felder existieren und was sie bedeuten
Welche Datentypen und Formate gelten
Welche Werte erlaubt sind (Validierungsregeln)
Welche Felder Pflicht sind und welche optional

Vollständiges Beispiel

Ein Data Contract für Bestelldaten im E-Commerce:

# Data Contract: Order Entity
# Version: 2.1.0
# Status: active

contract:
  id: "data-order-v2"
  name: "Order Data Contract"
  version: "2.1.0"
  owner: "team-commerce"
  domain: "orders"

  # Schema-Definition
  schema:
    type: "object"
    required:
      - order_id
      - customer_id
      - items
      - total
      - status

    properties:
      order_id:
        type: "string"
        format: "uuid"
        description: "Eindeutige Bestellnummer"
        example: "550e8400-e29b-41d4-a716-446655440000"

      customer_id:
        type: "integer"
        minimum: 1
        description: "Referenz zum Kunden"

      items:
        type: "array"
        minItems: 1
        items:
          type: "object"
          required: [product_id, quantity, unit_price]
          properties:
            product_id:
              type: "string"
            quantity:
              type: "integer"
              minimum: 1
              maximum: 999
            unit_price:
              type: "number"
              format: "decimal"
              description: "Preis in Euro, netto, 2 Dezimalstellen"
              example: 29.99

      total:
        type: "object"
        required: [net, gross, currency]
        properties:
          net:
            type: "number"
            format: "decimal"
            description: "Summe netto in Euro"
          gross:
            type: "number"
            format: "decimal"
            description: "Summe brutto in Euro"
          tax_rate:
            type: "number"
            enum: [0, 7, 19]
            description: "MwSt-Satz in Prozent"
          currency:
            type: "string"
            const: "EUR"

      status:
        type: "string"
        enum:
          - "draft"
          - "pending"
          - "confirmed"
          - "shipped"
          - "delivered"
          - "cancelled"
        description: "Aktueller Bestellstatus"

      timestamps:
        type: "object"
        properties:
          created_at:
            type: "string"
            format: "date-time"
          updated_at:
            type: "string"
            format: "date-time"

  # Validierungsregeln
  validation_rules:
    - id: "total_matches_items"
      description: "Summe muss mit Einzelposten übereinstimmen"
      formula: "total.net == SUM(items[].quantity * items[].unit_price)"

    - id: "gross_includes_tax"
      description: "Brutto = Netto + MwSt"
      formula: "total.gross == total.net * (1 + total.tax_rate/100)"

  # Prädikate
  predicates:
    - id: "schema_valid"
      check: "json_schema_validates"
    - id: "business_rules_pass"
      check: "all_validation_rules_pass"
    - id: "has_semantic_types"
      check: "all_fields_have_description"

Validierung in der Praxis

Bei jeder Datenübertragung wird der Contract automatisch geprüft:

# Validierungsergebnis
validation_result:
  contract_id: "data-order-v2"
  data_hash: "sha256:a1b2c3..."

  schema_check:
    passed: true
    errors: []

  business_rules:
    - rule: "total_matches_items"
      passed: true
      computed: 89.97
      expected: 89.97

    - rule: "gross_includes_tax"
      passed: true
      computed: 107.06
      expected: 107.06

  verdict: "VALID"
  validated_at: "2024-01-15T14:22:00Z"

Warum ist das wichtig?

Der Data Contract ist das gemeinsame Vokabular aller Systeme. Er verhindert Missverständnisse, macht Datenqualität messbar und ermöglicht automatische Validierung. Im Mensch + KI-Code Prozess ist er die Grundlage für verlässliche Kommunikation.

Im Mensch + KI-Code Prozess: Data Contracts werden gemeinsam mit API Contracts in Phase 3 definiert. Sie sind besonders wichtig für Change Classes "Normal" und "Critical", wo Datenintegrität verifiziert werden muss.