Data Contract Nedir? Veri Kırılmalarını Bitirin

Meta Description

Data contract nedir? Veri producer-consumer uyumunu şema, SLA ve kalite kurallarıyla garanti edin. Kırılmaları azaltmak için rehber.

Giriş

Veri tarafında en can yakıcı problem genelde “kod deploy etmedik ama raporlar bozuldu” cümlesiyle başlar. Bir ekip kolon adını değiştirir, başka ekip bunu günler sonra fark eder; dashboard’lar sapar, ML pipeline eğitim setini yanlış üretir, operasyon ekibi yanlış karar alır.

Data contract tam bu noktada devreye girer: Veri üreten (producer) ve veri tüketen (consumer) taraflar arasında net bir anlaşma koyar. “Bu tablo/stream şu şemada olacak, şu kalite kurallarını sağlayacak, şu zaman aralığında güncellenecek; değişiklik olursa şu süreç izlenecek” gibi.

Bu yazıyı okumalısınız çünkü data contract yaklaşımı; veri platformu ölçeklenirken kırılmaları, rework’ü ve ekipler arası sürtünmeyi ciddi biçimde düşürür. Üstelik sadece “dokümantasyon” değil; otomasyona bağlanabilen bir mühendislik pratiğidir.

Data Contract Nedir? (Ana Fikir)

Data contract, bir veri ürününün (tablo, event stream, API ile taşınan veri, feature store seti vb.) şu konularda resmileştirilmiş sözleşmesidir:

• Şema: Alanlar, tipler, zorunluluklar (required/optional)
• Anlam (semantics): Alanların iş anlamı (örn. amount hangi para birimi?)
• Kalite kuralları: Null oranı, unique, range, referential integrity
• SLA/SLO: Güncellenme sıklığı, gecikme (freshness), erişilebilirlik
• Versiyonlama ve değişiklik yönetimi: Breaking change nasıl yapılır?
• Sahiplik ve iletişim: Owner kim, incident’te kim aranır?

Amaç: “Veri boru hattı çalışıyor”dan öte, tüketicinin güvenle bağımlı olabileceği bir veri ürünü ortaya koymak.

Neden Data Contract Kullanmalıyım?

1) Sessiz kırılmaları yakalar

Kolon tipi string → int oldu; pipeline çalışıyor gibi görünür ama BI tarafında filtreler patlar. Contract + testler bu değişimi deploy anında yakalar.

2) Ekipler arası bağımlılıkları yönetir

Her tüketici tek tek “şu kolonu kullanıyorum, değiştirme” demek zorunda kalmaz. Contract, bunu sistematik hale getirir.

3) Veri kalitesi ölçülebilir olur

“Kalite iyi” yerine: null oranı %0.5 altında, freshness < 15 dk gibi net hedefler koyarsınız.

4) Regülasyon ve denetime yardımcı olur

Owner, lineage, değişiklik kayıtları; KVKK/GDPR benzeri süreçlerde “bu veri nereden geliyor?” sorusunu hızlandırır.

Data Contract’ın İçinde Neler Olmalı? (Pratik Checklist)

Aşağıdaki tablo, Türkiye’de ekiplerin en sık yaşadığı problemleri doğrudan hedefleyen “minimum uygulanabilir” contract içeriğini özetler:

Not: “Her şeyi baştan yazalım” yerine bu checklist ile başlayıp olgunlaştırmak genelde daha hızlı sonuç verir.

Adım Adım Data Contract Tasarlama

1) Veri ürününü netleştirin

Önce “contract” yazmadan, neye söz verdiğinizi tanımlayın:

• Tablo mu? (DWH)
• Event mi? (Kafka/PubSub)
• Feature set mi? (ML)

Gerçek hayat örneği: Ödeme ekibi payment_events stream’i yayınlıyor; fraud ekibi ve finans BI bunu tüketiyor.

2) Consumer’ları ve kritik alanları çıkarın

• Hangi ekipler tüketiyor?
• Hangi alanlar kritik?
• Hangi metrik/rapor bu veriye bağlı?

İpucu: En kritik alanlar genelde ID’ler, para birimi/tutar, zaman damgaları, durum (status) alanlarıdır.

3) Şema + iş anlamını birlikte yazın

Sadece “tip” yetmez. created_at UTC mi? status enum değerleri neler? Contract buna cevap vermeli.

4) Kalite kurallarını test edilebilir seçin

Kalite kuralları “niyet” değil, otomasyona bağlanabilir olmalı:

• not_null(customer_id)
• accepted_values(status, ["AUTHORIZED","CAPTURED","REFUNDED"])
• amount > 0
• event_time <= ingestion_time + 5m

5) Değişiklik yönetimini belirleyin

• Breaking change nedir? (kolon silme, tip değiştirme, anlam değiştirme)
• Deprecation süresi? (örn. 30 gün)
• Versiyonlama stratejisi? (semantic versioning benzeri)

6) CI/CD’ye bağlayın (en kritik kısım)

Contract dokümanı “wiki’de unutulmasın”. PR açılınca:

• Şema uyum testi
• Kalite testleri
• Breaking change kontrolü
• Gerekirse consumer onayı

Örnek Data Contract (YAML) + Basit Doğrulama

Aşağıdaki örnek, bir DWH tablosu için anlaşılır bir data contract taslağıdır.

# data-contracts/payments_v1.yaml
name: payments
version: 1.0.0
owner:
  team: payments-data
  slack: "#payments-data"
source:
  type: dwh_table
  platform: bigquery
  dataset: finance
  table: payments
sla:
  freshness_minutes_p95: 10
  availability_target: 0.999
schema:
  - name: payment_id
    type: string
    required: true
    description: "Ödeme işlemi benzersiz kimliği"
  - name: order_id
    type: string
    required: true
    description: "Sipariş kimliği"
  - name: amount
    type: decimal(12,2)
    required: true
    description: "Ödenen tutar"
    semantics:
      currency: TRY
  - name: status
    type: string
    required: true
    description: "Ödeme durumu"
    semantics:
      accepted_values: ["AUTHORIZED","CAPTURED","REFUNDED","FAILED"]
  - name: paid_at
    type: timestamp
    required: true
    description: "Ödemenin gerçekleştiği zaman (UTC)"
quality_rules:
  - rule: not_null
    column: payment_id
  - rule: unique
    column: payment_id
  - rule: range
    column: amount
    min: 0.01
  - rule: accepted_values
    column: status
    values: ["AUTHORIZED","CAPTURED","REFUNDED","FAILED"]
change_management:
  breaking_changes:
    - "column_removed"
    - "type_changed"
    - "semantics_changed"
  deprecation_days: 30

Basit bir doğrulama fikri: PR’da contract dosyası değiştiğinde, şema değişimini kontrol eden bir script çalıştırın.

# scripts/check_breaking_change.py
import sys

BREAKING = {
    "removed_column",
    "type_changed",
}

def diff_schema(old_cols, new_cols):
    old = {c["name"]: c for c in old_cols}
    new = {c["name"]: c for c in new_cols}

    for name in old:
        if name not in new:
            return "removed_column", name
        if old[name]["type"] != new[name]["type"]:
            return "type_changed", name
    return None, None

# Gerçekte old/new YAML dosyalarını okuyacaksınız.

# Burada sadece iskelet gösteriyoruz.
if __name__ == "__main__":

# mock
    old_schema = [{"name":"amount","type":"decimal(12,2)"}]
    new_schema = [{"name":"amount","type":"string"}]

    kind, col = diff_schema(old_schema, new_schema)
    if kind in BREAKING:
        print(f"BREAKING CHANGE: {kind} on {col}")
        sys.exit(1)
    print("OK")

Bu yaklaşımı GitHub Actions/GitLab CI’a bağlayarak breaking change’i merge edilmeden yakalayabilirsiniz.

Gerçek Hayat Senaryosu: “Kolon Adı Değişti, Finans Raporu Bozuldu”

Diyelim ki paid_at alanı “daha net” olsun diye payment_time olarak değiştirildi.

• BI dashboard paid_at ile günlük tahsilat raporu çekiyor.
• Pipeline çalışıyor, tablo doluyor; ama dashboard boş.

Data contract ile çözüm:

1. paid_at kaldırma işlemi “breaking change” olarak işaretlenir.
2. CI, PR’ı kırmızıya düşürür.
3. Producer iki seçenekten birini seçer:
   • paid_at alanını 30 gün deprecated tutar, paralel payment_time ekler (non-breaking)
   • major version çıkarır (v2), consumer’lar planlı göç eder

Sonuç: Sürpriz üretim hatası yerine planlı geçiş.

Uygulamada En İyi Pratikler (Kısa ve Etkili)

• Contract’ı “data product” seviyesinde sahiplenin: Owner ve iletişim kanalı şart.
• Semantics’i yazmadan bırakmayın: Para birimi, timezone, enum değerleri en çok sorun çıkaranlar.
• Önce en kritik dataset’lerden başlayın: Ödeme, sipariş, kullanıcı, envanter.
• Kalite kurallarını az ama güçlü seçin: 5 iyi kural, 50 belirsiz kuraldan daha iyi.
• Versiyonlama disiplinini oturtun: Breaking change = major.

Sık Sorulan Sorular (FAQ)

1) Data contract ile schema registry aynı şey mi?

Hayır. Schema registry genelde şemayı yönetir. Data contract ise şemaya ek olarak SLA, kalite kuralları, sahiplik ve değişiklik süreci gibi geniş bir kapsamı içerir.

2) Data contract yalnızca Kafka/event streaming için mi?

Hayır. DWH tabloları, lakehouse dataset’leri, feature store’lar hatta veri API’leri için de uygulanır.

3) Data contract yazmak geliştirmeyi yavaşlatır mı?

İlk kurulumda az bir efor getirir; fakat uzun vadede prod kırılmalarını ve iletişim maliyetini düşürerek toplam hızı artırır.

4) Minimum viable data contract ile neyi hedeflemeliyim?

En azından: şema + owner + 3-5 kalite kuralı + freshness SLA + breaking change tanımı.

Sonuç

Data contract, veri üreten ve tüketen ekipler arasında güven inşa eden, kırılmaları azaltan ve veri kalitesini ölçülebilir hale getiren bir yaklaşımdır. Şema, iş anlamı, kalite kuralları ve SLA’yı tek bir yerde toplayıp CI/CD’ye bağladığınızda “sessiz veri hataları” ciddi ölçüde azalır.

Bir sonraki adım: Bugün en kritik 1 dataset’iniz için küçük bir contract çıkarın ve PR sürecine “breaking change” kontrolünü ekleyin. Deneyimlerinizi ve yaşadığınız kırılma örneklerini yorumlarda paylaşırsanız, sektör pratiklerinden yeni bir derleme de çıkarabiliriz.