Sabah 08:30. Kahveni henüz almışsın, bilgisayarı açıyorsun. Slack’te kırmızı bildirimler, e-postada patron mesajları. Dashboard (gösterge paneli) açılmıyor ya da en kötüsü açılıyor ama rakamlar saçma. ETL gece sessiz sedasız hata alıp durmuş. Tablolar boş. Ve patronun sana bakışı şunu söylüyor: “Bu raporlara hiç güvenmeyelim mi?”

Bu manzara veri mühendisliği dünyasında o kadar yaygın ki, neredeyse sektörün ortak şakası haline gelmiş. Ama o sabahları yaşayanlar için hiç komik değil. Sorunu araştırıyorsun, 30 dakika sonra gerçeği öğreniyorsun: upstream (kaynak taraftaki) uygulama geliştiricisi bir tablo şemasını (schema) değiştirmiş. Sütun adını rename etmiş, yeni bir alan eklemiş ya da bir alanı sessizce kaldırmış. Kimseye sormadan. Çünkü onun işi kendini kurtarmak, kendi özelliğini geliştirmek, aşağıdakileri kim takar.

Ve sen işte bu yüzden o sabah kahveni soğutuyorsun.

Sorunun Anatomisi: Neden Bu Kadar Sık Oluyor?

Veri ekipleri, çoğu zaman canlı sistemlere ve servislere bağımlıdır. Bu sistemlerden gelen veriler, veri ambarına (data warehouse), lakehouse’a vb. düşerek farklı downstream (aşağı yönlü) süreçlerin temelini oluşturur. Ancak bu sistemlerin sorumluluğunu taşıyanlar mesela yazılım geliştiricileri, söz konusu veri bağımlılıklarından genellikle habersizdir. Bu yüzden servislerinde bir güncelleme yaptıklarında ve bu güncelleme bir şema değişikliğine yol açtığında, o sisteme bağlı tüm veri süreçleri bir anda çakılır. [1]

Patron haklı güvenmemekte. Çünkü güvensizliğinin gerçek bir dayanağı var. Gartner’a göre kötü veri kalitesi, şirketlere ortalama yılda 12,9 milyon dolar’a mal oluyor. [22] IBM ise yalnızca ABD’de iş dünyasının yıllık 3,1 trilyon dolar kaybettiğini tespit etti. [21] Bu rakamlar soyut görünüyor, o yüzden somutlaştıralım: Çalışanlar zamanlarının yüzde 27’ye kadar olan kısmını hatalı veriyi düzeltmekle geçiriyor. [27]

Yani sabah gelen o Slack mesajları, salt teknik bir arıza değil; para ve zaman kaybı.

Peki çözüm ne? Geliştiriciyi uyarmak mı? Her değişiklikten önce “bana sor” mu demek? Çalışır, kısa vadede. Ama büyük bir organizasyonda, onlarca takım olduğunda, bu insan bazlı koordinasyon kaçınılmaz olarak bir yerden çatlar. Veri sözleşmeleri (data contracts) tam bu sorunu çözmek için tasarlanmıştır: upstream (kaynak taraftaki) serviste yapılan küçük bir değişiklik — sütun adının değiştirilmesi, yeni bir enum değeri eklenmesi, farklı bir zaman damgası formatı — saatler sonra dashboard’ların boş kalmasına, makine öğrenmesi modellerinin yanlış sonuç üretmesine ve bir veri mühendisinin gece 03:00’te hata ayıklamasına neden olabilir. [6]

Veri Sözleşmesi (Data Contract) Nedir?

Data Contracts, veri üreticileri (data producers) ile veri tüketicileri (data consumers) arasında yapılan bağlayıcı anlaşmalardır. Bu anlaşmalar, verinin yapısını, nasıl doğrulanacağını ve iletileceğini tam olarak tanımlar. [4]

Ama “anlaşma” derken bir Word belgesi ya da e-posta zinciri düşünmeyin. Geleneksel dokümantasyondan farklı olarak, veri sözleşmeleri genellikle YAML gibi deklaratif (bildirimsel) formatlarda yazılır, sürüm kontrolünde (version control) tutulur ve pipeline çalışması ya da dağıtım sırasında otomatik olarak doğrulanır. [13]

Yani kağıt üzerinde değil, kod olarak. Git’e gidiyor, CI/CD (Continuous Integration/Continuous Deployment – Sürekli Entegrasyon/Sürekli Dağıtım) süreçlerine dahil ediliyor. Sözleşmeyi ihlal eden bir değişiklik mi? Build başarısız oluyor. Geliştiricinin o tabloyu “gafıya göre” değiştirmesi artık o kadar kolay değil.

Daha sade bir dille anlatmak gerekirse: sen bir restoran işletiyorsun ve tedarikçin her gün farklı boyutta domates gönderip “ne bulursam gönderiyorum” diyorsa, o tedarikçiyle oturup açık bir anlaşma yapıyorsun. Bu anlaşmada domateslerin hangi boyutta, ne zaman, hangi kalitede geleceği net bir şekilde belirlenmiş oluyor. Tedarikçi bunu imzalıyor ve artık siz de her sabah restorana gidince “bugün ne sürpriz olacak?” diye sormak zorunda kalmıyorsunuz.

Veri Sözleşmesinin İçinde Ne Var?

Bir veri sözleşmesi genellikle şu bileşenleri içerir:

Şema tanımı (Schema definition): Hangi sütunlar var, veri tipleri (data types) ne, hangi alanlar boş bırakılamaz (not null)? Şema tanımları, JSON Schema, Apache Avro veya Protocol Buffers gibi standart formatlar kullanılarak yapılır ve farklı sistemler arasında birlikte çalışabilirliği garanti eder. [4]

Kalite kuralları (Quality rules): Satır sayısı belirli bir eşiğin altına düşmemeli, belirli alanlar boş olmamalı, zaman damgası verisinin tazeliği (freshness) en fazla 24 saat olmalı gibi kurallar. Bu kalite kontrolleri SodaCL, Monte Carlo veya dbt-tests gibi araçlarla yazılabilir. [12]

Anlambilimsel beklentiler (Semantic expectations): Veri sözleşmeleri yalnızca şemayı değil, anlambilimi de kapsar. Örneğin, bir alanda length (uzunluk) değerleri inç cinsinden tutuluyorsa, bu değerlerin aniden santimetreye çevrilmesi, API imzası değişmeden de olsa bir sözleşme ihlali sayılır. [8]

Sahiplik ve iletişim bilgileri (Ownership & contact info): Kim sorumlu? Bir sorun çıktığında kimi arayacağız?

SLA (Service Level Agreement – Hizmet Seviyesi Sözleşmesi): Veri ne zaman hazır olmalı? Geç gelmesi ne anlama gelir? [10]

Kullanım koşulları (Usage terms): Bu veri ne amaçla kullanılabilir, hangi amaçlarla kullanılamaz? [12]

Teknik Olmaktan Önce Kültürel Bir Değişim

Burada önemli bir parantez açmak gerekiyor. Veri sözleşmeleri bir araçtan çok bir zihniyet meselesi.

Veri sözleşmeleri her şeyden önce, veri merkezli işbirliğine (data-centric collaboration) doğru kültürel bir değişimdir. [8] Teknolojiyi kurarsınız, YAML dosyalarını yazarsınız, CI/CD’ye bağlarsınız ama organizasyonda veri üretenler ile tüketenler arasında gerçek bir mutabakat yoksa, o sözleşmeler işlevsiz belgelerden ibaret kalır.

Veri üreten mühendis şunu anlamalı: “Bu tablo benim tablo değil. Benden downstream’de onu kullanan 5 farklı ekip var. Ben şemayı değiştirirsem onların sistemleri çöker.” Veri tüketen analist veya mühendis de şunu anlamalı: “Karşı taraftan makul olmayan talepte bulunursam, o tabloyu kullanan başka tüketicilere zarar verebilirim.”

En büyük zorluklar teknik değil, organizasyoneldir. Farklı ekiplerin farklı öncelikleri vardır. Veri üreticilerinden ek iş yükü beklendiğinde doğal olarak şunu sorarlar: ‘Benim için ne anlamı var?’ Bu yüzden liderlik desteği ve kültür değişimi şarttır. [1]

Yani patron da bu sürecin içinde. Veri sözleşmeleri, sadece mühendislerin aralarında çözeceği teknik bir mesele değil; yöneticilerin de sahip çıkması gereken bir kurum kültürü meselesi.

Pratikte Nasıl Çalışıyor? Araçlara Bir Göz Atalım

Teoride güzel, pratikte nasıl işliyor? Birkaç yaygın araca bakalım.

dbt Contracts (dbt Sözleşmeleri)

Zaten dbt (data build tool) kullanıyorsanız, buradan başlamak en kolay yol. dbt model sözleşmeleri, dönüşüm (transformation) sınırındaki yanlışlıkla gerçekleşen şema değişikliklerini önlemek için tasarlanmıştır. YAML konfigürasyonunda tanımlanan dbt sözleşmeleri, bir modelin çıktısının materialization (somutlaştırma) işlemi öncesinde beklenen sütun seti, veri tipleri ve kısıtlamalarla eşleşip eşleşmediğini doğrular. Eşleşmezse dbt run başarısız olur. [13]

Basit bir örnek:

models:
  - name: dim_orders
    config:
      materialized: table
      contract:
        enforced: true
    columns:
      - name: order_id
        data_type: int
        constraints:
          - type: not_null
      - name: order_type
        data_type: string

Bu konfigürasyonla, biri order_id sütununu int’ten string’e çeviren bir değişiklik yaparsa dbt build hemen hata verir. [18]

Data Contract CLI ve ODCS (Open Data Contract Standard)

Data Contract CLI, YAML formatında veri sözleşmeleri oluşturmanızı, doğrulamanızı ve test etmenizi sağlayan açık kaynak bir araçtır. dbt, Avro, JSON Schema, SQL DDL gibi pek çok formata dönüştürebilir, bu formatlardan da okuyabilirsiniz. [11] Open Data Contract Standard (ODCS) ise OpenAPI spesifikasyonu gibi düşünülebilecek, veri setleri için ortak bir sözleşme formatı tanımlamayı amaçlayan açık bir inisiyatiftir. [12]

Soda Data Contracts

Soda, veri pipeline’ının her bileşeni arasında veri kalitesini doğrulayan bir yaklaşım sunar. Her pipeline adımından sonra veri sözleşmesini doğrulayarak verinin bir sonraki bileşene geçmeden önce belirtilen kalite standartlarını karşılamasını garantiler. [14]

Kafka Schema Registry (Kafka Şema Kaydı)

Gerçek zamanlı veri akışı (real-time data streaming) ile çalışıyorsanız Kafka Schema Registry devreye giriyor. Event streaming platformları olan Kafka Schema Registry, şema uyumluluğunu zorunlu kılarak üreticiler ve tüketiciler arasındaki gerçek zamanlı veri sözleşmelerini yüksek hacimli senaryolarda düşük gecikme süresiyle uygular. [2]

CI/CD’ye Entegrasyon: Sözleşmeyi Canlı Tutan Şey

Sözleşmeyi yazmak yeterli değil. O sözleşmenin ihlal edildiği an otomatik olarak uyarı vermesi ya da geliştirme sürecini durdurması gerekiyor.

GitHub/GitLab workflow’ları giderek daha fazla sözleşme “bekçisi” olarak görev yapıyor. Şema değişiklikleri üretime ulaşmadan önce otomatik kontroller çalışıyor. [2]

Bunun anlamı şu: Geliştirici bir PR (Pull Request – Çekme İsteği) açıyor, tabloda bir sütunu değiştiriyor. CI pipeline başlıyor, veri sözleşmesi kontrolü yapılıyor. Sözleşme ihlal edilmişse PR merge edilemiyor. “Ama ben bunu geliştirmedim, geriye gidip sözleşmeyi güncellemedim” diyemez. Önce sözleşme güncellenir, tüketiciler bilgilendirilir, sonra değişiklik yapılır.

Bu yaklaşıma “shift-left” (sola kaydırma) deniyor. Sorunları üretimde yakalamak yerine geliştirme aşamasında yakalamak. Verinin alındığı an yakalamak ile daha sonra yakalamak arasındaki maliyet farkı 1x’ten 10x’e ve 100x’e çıkabilir. [29]

Data Mesh ve Data Contracts

Veri örgüsü (data mesh) mimarisini bilen ya da bu yolda olan arkadaşlar için veri sözleşmeleri ayrı bir önem taşıyor. Data mesh, veri sahipliğini domain (alan) takımlarına dağıtırken, self-serve altyapı, standartlaştırılmış veri sözleşmeleri ve otomatik yönetişim süreçleri aracılığıyla yönetişim standartlarını korur. [9]

Veri örgüsü mimarisinde veri sahipliği domain takımları arasında dağılmış durumdadır. Veri sözleşmeleri, veri üreticileri ile tüketicileri arasındaki beklentileri resmileştirerek takımları veri standartları konusunda hizalar ve verinin farklı domainler arasında akışı sırasında veri kalitesi sorunlarının riskini azaltır. [20]

Versiyonlama (Versioning): Sözleşmelerin Evrimi

Sözleşmeler statik belgeler değil, yaşayan belgeler olmalı. Zaman içinde iş gereksinimleri değişiyor, yeni alanlar gerekiyor, eskiler kullanılmaz oluyor. İyi tasarlanmış sözleşmeler değişmezlik değil, stabilite sınırları tanımlar. Tüketicilerin neye güvenebileceğini belirtirken üreticilerin iç mantığı evrimleştirmesine, yeni alanlar eklemesine ya da yeni versiyonlar sunmasına izin verir. Hedef sıfır değişiklik değil, güvenli değişikliktir. [13]

Pratik olarak bunun anlamı şu: Büyük kırılıcı (breaking) değişiklikler için sözleşmenin versiyonu yükseltilir (v1’den v2’ye). Tüketicilere geçiş süresi tanınır. Küçük geriye uyumlu (backward compatible) değişiklikler için mevcut sözleşme güncellenir. Şema değişikliklerini mevcut pipeline entegrasyonlarını bozmadan modifiye edebilmek için on_schema_change: append gibi mekanizmalar ve versiyonlama önerilmektedir. [3]

Nereden Başlamalıyız?

Bu noktaya kadar okuduysanız şunu düşünüyor olabilirsiniz: “Tamam, anlıyorum. Ama şirkette tek başıma bunları nasıl uygulayacağım? Hangi tablodan başlayacağım?”

Her veri setini sözleşme altına almak ne mümkün ne de gerekli. Kritik dashboard’lar ve temel makine öğrenmesi girdileri gibi yüksek etkili verilerle başlayın. [1]

Somut adımlar şöyle önerilir:

1. Küçük, etki büyük: En çok kullanılan ve en kritik dashboard’ın beslendiği tablodan başlayın. Bir veri sözleşmesi taslağı hazırlayın, ilgili geliştiriciyle oturun.

2. Kültür altyapıya önce gelir: Teknik araçları kurmadan önce “bu neden var” sorusunu herkese cevaplatın. Veri üreticisi de bu sürecin gönüllüsü olmalı. Veri üreticileri, tüketiciler, veri mühendisleri, veri bilimciler ve iş, BT, hukuk ve uyum departmanlarından temsilciler dahil olmak üzere farklı paydaşları dahil edin. [3]

3. Otomasyonu kademeli kurun: Önce manuel kontrollerle başlayın. Süreç otururken CI/CD entegrasyonunu ekleyin. Mükemmel olmayı beklerseniz asla başlayamazsınız.

4. Sözleşmeleri güncelin: Veri sözleşmeleri yalnızca tanımlandıkları veri ürünleriyle eş zamanlı evrimleştiklerinde işe yarar. [2] Statik bir belgeyse, kısa sürede gerçekten sapacak ve kimse güvenmeyecek.

5. Yönetim desteğini alın: Burada vurgu yapalım. Liderliğin, kötü veri olaylarının post-mortem (olay sonrası analiz) raporlarını görmesini ve veri kesintilerinin iş operasyonlarına gerçek etkisini anlamasını sağlayın. Liderlik gerçek etkiyi gördüğünde, sözleşmeler için destek çok daha güçlü hale gelir. [1]

Patrona Nasıl Anlatılır?

Teknik olmayan yöneticilere veri sözleşmelerini anlatmanın en iyi yolu, onların dilinden konuşmak. Tedarik zinciri analojisi işe yarıyor:

“Düşün ki fabrikana her gün malzeme geliyor ama malzemelerin kalitesi, boyutu ve zamanlaması tamamen tedarikçinin keyfine bırakılmış. Hiçbir sözleşme yok. Sonra da üretim durduğunda neden dururmuş diye soruluyor. Veri sözleşmeleri, veri tedarikçilerimizle yaptığımız resmi, otomatik kontrollü tedarik sözleşmeleridir. Sabah gelince ‘neden çalışmıyor’ diye sormak zorunda kalmayız.”

Bu, patrona güven veriyor. Çünkü artık “umuyoruz ki çalışır” yerine “kontrol edilir ve çalışır” moduna geçiyorsunuz.

Sonuç: Sorunların Peşinden Koşmak mı, Önlemek mi?

Veri mühendisliği dünyasında iki tip ekip var: sabah gelince “ne bozulmuş?” diye araştıranlar ve “ne beklediğimiz şeyler doğrulandı” diye kontrol edenler. İkincisi olmak için veri sözleşmeleri tek yol değil ama bugün en güçlü araçlardan biri.

Veri sözleşmeleri, statik spesifikasyonlardan, verinin ilerlemesine izin verip vermeyeceğini etkileyen aktif kontrol noktalarına dönüştüğünde, sözleşmeler statik özellikler olmaktan çıkıp operasyonel güvencelere dönüşür. [15]

Evet, başlangıçta ekstra çaba gerektirir. Evet, organizasyonel bir değişim ister. Evet, patronu, geliştiriciyi, analisti aynı masaya oturtmayı gerektirir. Ama sabah gelince soğuyan kahve artık o ETL hata mesajı yüzünden değil, bir randevuya geç kaldığın için soğuyacak.

Veri sözleşmeleri, bir araç değil bir olgunluk göstergesi. Ve o olgunluğa giden yol, bugün ilk küçük adımla başlar.

Kaynaklar

[1] Monte Carlo Data — Data Contracts Explained: How They Work, Importance, & Best Practices — https://www.montecarlodata.com/blog-data-contracts-explained/

[2] Atlan — Data Contracts Explained: Key Aspects, Tools, Setup in 2026 — https://atlan.com/data-contracts/

[3] DataCamp — What Are Data Contracts? A Beginner Guide with Examples — https://www.datacamp.com/blog/data-contracts

[4] Airbyte — Data Contracts: What Are They & Do You Need Them? — https://airbyte.com/data-engineering-resources/data-contracts

[5] Gable.ai — 8 Common Data Engineering Best Practices — https://www.gable.ai/blog/data-engineering-best-practices

[6] Medium / QuarkAndCode — Data Contracts Explained: Definition, Examples, and Best Practices — https://medium.com/@QuarkAndCode/data-contracts-explained-definition-examples-and-best-practices-ab296a4178d1

[7] Schiller & Larochelle — Data Engineering Best Practices (Google Books) — https://books.google.com/books/about/Data_Engineering_Best_Practices.html?id=vr4gEQAAQBAJ

[8] Data Products Substack — An Engineer’s Guide to Data Contracts – Pt. 1 — https://dataproducts.substack.com/p/an-engineers-guide-to-data-contracts

[9] Data Engineering Weekly — The State of Data Engineering in 2024: Key Insights and Trends — https://www.dataengineeringweekly.com/p/the-state-of-data-engineering-in

[10] Databricks Community — Data Contract Implementation Best Practices — https://community.databricks.com/t5/data-engineering/data-contract-implementation-best-practices/td-p/96740

[11] Data Contract CLI — Enforce Data Contracts — https://cli.datacontract.com/

[12] Data Contract Specification — ODCS v0.9.0 — http://datacontract.com/versions/0.9.0/

[13] Soda.io — The Definitive Guide to Data Contracts — https://soda.io/blog/guide-to-data-contracts

[14] Soda Documentation — Set Up Data Contracts — https://docs.soda.io/soda/data-contracts.html

[15] Soda.io — Guide to Data Contracts (Full) — https://soda.io/old/blog/guide-to-data-contracts

[16] Medium / Dr. Jarkko Moilanen — Emerging “Everything as code” in the Data Contract Standards — https://medium.com/exploring-the-frontier-of-data-products/emerging-everything-as-code-in-the-data-contract-standards-10ad7ad76fbb

[17] GitHub — datacontract/datacontract-cli — https://github.com/datacontract/datacontract-cli

[18] dbt Developer Hub — Contract Configuration Reference — https://docs.getdbt.com/reference/resource-configs/contract

[19] Soda Documentation — Write a Data Contract — https://docs.soda.io/data-contracts/data-contracts-write

[20] DataCamp — Data Contracts with dbt – Schema.yaml Examples — https://www.datacamp.com/blog/data-contracts

[21] Anodot — The Costs of Poor Data Quality — https://www.anodot.com/blog/price-pay-poor-data-quality/

[22] Esri ArcNews — Data Quality Across the Digital Landscape — https://www.esri.com/about/newsroom/arcnews/data-quality-across-the-digital-landscape

[23] ZoomInfo — The True Cost of Poor Data Quality — https://pipeline.zoominfo.com/operations/poor-data-quality-impact

[24] Data Sleek — The True Cost of Poor Data Quality and How to Fix It — https://data-sleek.com/blog/cost-of-poor-data-quality/

[25] LightsOnData — Estimating the Cost of Poor Data Quality in 5 Steps — https://www.lightsondata.com/estimating-cost-poor-data-quality/

[26] IndustrySelect — Measuring the High Cost of Bad Contact Data — https://www.industryselect.com/blog/measuring-the-high-cost-of-bad-contact-data

[27] Actian — The Costly Consequences of Poor Data Quality — https://www.actian.com/blog/data-management/the-costly-consequences-of-poor-data-quality/

[28] Acceldata — The Hidden Cost of Poor Data Quality & Governance — https://www.acceldata.io/blog/the-hidden-cost-of-poor-data-quality-governance-adm-turns-risk-into-revenue

[29] Monte Carlo Data — The Alarming Cost Of Poor Data Quality — https://www.montecarlodata.com/blog-the-cost-of-poor-data-quality/

[30] Insurance Thought Leadership — The True Cost of Big (Bad) Data — https://www.insurancethoughtleadership.com/our-partners/true-cost-big-bad-data