Data Contract Protokolü: Pact, AsyncAPI ve Üretim Pratiği 2026

Data contract nedir? Veri üreten servis (producer) ile veri tüketen servis (consumer) arasındaki şema, semantik, SLA ve sahiplik kurallarını makine-okunabilir ve sürüm-kontrollü bir doküman olarak tanımlayan sözleşmedir. 2024 sonrası data mesh ve event-driven mimarilerin yaygınlaşmasıyla data contract pratiği, üretim sistemlerinde kırılma maliyetini ortalama yüzde 40-60 oranında düşüren ana mekanizma haline geldi. Bu yazı, Pact ile consumer-driven contract testing, AsyncAPI ile event şema sözleşmeleri ve Open Data Contract Standard (ODCS v3.0.0 — Bitol projesi, LF AI & Data Foundation altında, Mayıs 2024) gibi standartların gerçek üretim hatlarında nasıl bir araya geldiğini, tedarikçi karşılaştırması ve karar çerçevesiyle anlatır. Hedef kitle: data platform ekibi liderleri, data engineer’lar ve mimarisinde kafka / Snowflake / dbt / Iceberg gibi katmanları olan ekipler.

Data contract pratiğini doğru kuran ekiplerde tipik göstergeler: schema-related production incident sayısı çeyrek bazda yüzde 55-70 düşüş, downstream pipeline restoration süresi (MTTR) saatlerden dakikalara iniyor ve veri kalitesi SLA ihlal oranı yüzde 3’ün altına çekilebiliyor. Bu rakamlar Atlan, Monte Carlo ve dbt Labs’ın 2024 müşteri raporlarıyla tutarlı; ancak yöntem doğru uygulanmazsa contract’lar bürokratik döküman çöplüğüne dönüşür.

Data Contract Nedir ve Neyi Sözleşmeye Bağlar?

Klasik API kontratı (REST/gRPC) sentaktik şemayı (alan adı, tip, zorunlu mu) tanımlar. Data contract bunun üstüne dört boyut ekler: semantik (alan ne anlama geliyor, hangi iş varlığını temsil ediyor), kalite (null oran, freshness penceresi, kabul edilebilir gecikme), SLA/SLO (uptime, p95 latency, throughput taahhüdü), sahiplik & yaşam döngüsü (kim sahip, deprecate süreci, breaking change politikası).

Open Data Contract Standard (ODCS), bu dört boyutu YAML formatında modelleyen LF AI & Data Foundation onaylı standarttır. ODCS v3.0.0 (Mayıs 2024) ile schema, quality, servicelevels, support ve roles blokları zorunlu hale geldi. Standart, GitHub’da bitol-io/open-data-contract-standard reposunda; CNCF benzeri açık governance modeliyle yönetiliyor. Alternatif yaklaşımlar arasında Data Contract Specification (datacontract.com — Stefan Negele liderliğinde topluluk projesi) ve şirket-içi YAML şablonları var; ancak ODCS endüstri konsensüsüne en yakın taban.

Pratik tanım: data contract, bir Kafka topic’i, bir Snowflake tablosu, bir dbt model çıktısı veya bir REST endpoint’i için “bu veriyi şöyle üreteceğim, sen şöyle tüketebilirsin” diyen, CI’da test edilebilen, sürüm-kontrollü dosyadır.

Boyut	API Kontratı (OpenAPI 3.1)	Data Contract (ODCS v3)	Event Contract (AsyncAPI 3.0)
Sentaktik şema	Var (JSON Schema)	Var (logical/physical types)	Var (Avro/JSON/Protobuf)
Semantik açıklama	Açıklama alanı (opsiyonel)	Zorunlu (description + business term)	Açıklama + tag
Kalite kuralları	Yok	Var (quality block — SodaCL / Great Expectations entegre)	Yok (kalite kanal-spesifik)
SLA / SLO	Yok (haricen)	Var (servicelevels)	Var (bindings içinde)
Sahiplik	Opsiyonel (info.contact)	Zorunlu (roles, support)	Opsiyonel
Tipik tüketici	UI, mobil, B2B API	Analytics, BI, ML feature store	Microservice, stream processor
Versiyonlama	SemVer (URL/header)	SemVer (file + registry)	SemVer (channels)

Tablo gösteriyor: data contract bir API spec değildir, ancak API spec’i besler. Üretim sisteminde üç format genelde bir arada bulunur — API katmanı için OpenAPI, event katmanı için AsyncAPI, depo katmanı için ODCS. Data Mesh mimarisinde her domain kendi data product’larını bu üç katmanlı sözleşmeyle yayımlar.

Neden 2026’da Data Contract Zorunlu Hale Geldi?

2019-2022 arası “schema registry yeterli” tezi popülerdi: Confluent Schema Registry veya AWS Glue Schema Registry üzerinde Avro şemasını compatibility kuralıyla yönetirsin, kırılma olmaz. Üretim verisi gösterdi ki bu varsayım yanlış — şema geriye uyumlu olabilir ama anlam (semantik) kırılabilir. Örneğin user_id alanı string’den string’e geçer ama içerik UUID’den email hash’ine değişirse downstream ML modeli sessizce bozulur. Schema registry bunu yakalayamaz.

Üç sektör trendinin kesişimi data contract pratiğini zorunlu yaptı:

• Data mesh adopsiyonu: Zhamak Dehghani’nin 2019 makalesinden sonra büyük şirketlerde domain-owned data ürünlerine geçiş başladı. Sahibi belirsiz veriyi tüketmek = production incident.
• Real-time analytics: Kafka, Flink, ClickHouse gibi stream-first sistemler batch’ten farklı olarak şema değişikliğini saniyeler içinde production’a taşır.
• Veri ürünleri için SLA: Internal müşteriler (ML team, BI, regülatör raporlama) veri kalitesi ve freshness’a numeric taahhüt istiyor.

Gartner’ın 2024 Data Engineering Hype Cycle raporunda “Data Contracts” Innovation Trigger’dan Peak of Inflated Expectations’a geçti — yani konuşma çok, pratik az; ama 2026 itibarıyla Slope of Enlightenment’a doğru hareket var. dbt Labs’ın 2024 State of Analytics Engineering anketinde katılımcı şirketlerin yüzde 38’i data contract pratiği kurmaya başladığını, yüzde 14’ünün üretimde tam uyguladığını bildirdi.

Yaklaşım	Şema	Semantik	Kalite	SLA	Sahiplik	Üretim olgunluğu
Sadece Schema Registry (Confluent/Glue)	Evet	Hayır	Hayır	Hayır	Hayır	Düşük — sessiz kırılma riski
OpenAPI tek başına	Evet	Kısmî	Hayır	Hayır	Kısmî	API odaklı, veri için yetersiz
Pact contract test	Evet (consumer-driven)	Test üzerinden	Test üzerinden	Hayır	Otomatik	HTTP/event için kuvvetli
AsyncAPI + Schema Registry	Evet	Evet	Hayır	Channel binding	Evet	Event-driven için standart
ODCS v3 (data contract)	Evet	Evet	Evet	Evet	Evet	Tam — emerging standard
datacontract.com CLI	Evet	Evet	Evet (Soda/GE entegre)	Evet	Evet	Pratik — açık kaynak

Tek bir araç tüm boyutları çözmüyor; pratik mimari: ODCS dosyası “ground truth” + Pact ile consumer test + AsyncAPI ile event şema dokümantasyonu + Schema Registry ile runtime enforcement.

Pact ve Consumer-Driven Contract Testing

Pact (pact.io — Smartbear desteğiyle açık kaynak, GitHub’da yaklaşık 4.2k yıldız ana repoda) consumer-driven contract testing pattern’inin de-facto referans implementasyonu. Klasik integration test’in tersine: tüketici (consumer) önce üreticiden ne beklediğini tanımlayan bir test yazar; bu test bir “pact” dosyası (JSON) üretir; üretici (provider) bu pact dosyasını kendi CI’sında çalıştırıp doğrular. Pact Broker (veya Pactflow SaaS) bu dosyaların ortak deposu.

Pact’ın data contract bağlamında değeri: provider değişiklik yapmadan önce her consumer’ın gerçek beklentisini görür. Şema geriye uyumlu olsa bile, eğer bir consumer alan değerini özel bir formatta bekliyorsa (örnek: timestamp ISO 8601 ama o consumer epoch ms parse ediyor), pact bunu yakalar.

• Avantaj: Tüketici beklentisi otomatik test, deployment öncesi feedback.
• Avantaj: 12+ dil desteği (Java, .NET, Go, Python, Node.js, Ruby, Rust, JVM family).
• Dezavantaj: Pact mock’lar her zaman gerçek davranışı yansıtmaz — provider verification şart.
• Dezavantaj: Event-driven (Kafka, RabbitMQ) için Message Pact ayrı bir yetenek; entegrasyonu HTTP’den daha karmaşık.
• Ne zaman seç: Microservice’lerarası HTTP/JSON-RPC etkileşimleri çok ve consumer sayısı 3+ ise.

Pact’ı sadece HTTP için kullanmak yaygın yanılgı; Pact Message Provider/Consumer ile Kafka mesajları için de aynı pattern uygulanabilir. Ancak Kafka’da AsyncAPI + Schema Registry kombinasyonu daha ergonomik çünkü runtime enforcement (compatibility check) zaten Kafka cluster düzeyinde çalışıyor. Event-driven mimarilerde Kafka ile beraber AsyncAPI tipik tercih.

AsyncAPI 3.0 ve Event Sözleşmeleri

AsyncAPI Initiative’nin (Linux Foundation altında) yayımladığı AsyncAPI 3.0.0 spec (Aralık 2023), event-driven sistemler için OpenAPI’nin karşılığı. Channels, operations, messages, servers ve bindings konseptleriyle Kafka, AMQP, MQTT, NATS, Kinesis gibi her broker’ı modeller. 3.0 sürümüyle channels ve operations ayrıştırıldı — aynı channel’ı hem publish hem subscribe olarak farklı operasyonlarla tanımlayabilirsin.

Pratik kullanım: bir Kafka topic için AsyncAPI spec yazılır, içine Avro/JSON schema referansı (genelde Schema Registry URL’i) gömülür, channel binding’inde retention, partition count, cleanup policy gibi runtime özellikler belirtilir. asyncapi-cli ile spec’ten istemci kodu (Java, TypeScript, Python) üretilebilir.

Özellik	AsyncAPI 2.6	AsyncAPI 3.0	Avantaj
Channel-operation ayrımı	Birleşik	Ayrı	Aynı channel’da farklı op’lar
Reply operations	Sınırlı	First-class	Request/reply pattern desteği
Server tags & metadata	Var	Genişletildi	Multi-env yönetimi
Code generation	Var (Modelina)	İyileştirilmiş Modelina v3	Daha az boilerplate
Backwards compat (2.6)	—	Migration script var	Aşamalı geçiş mümkün

Schema Registry ile entegrasyon: Confluent Schema Registry, Avro/Protobuf/JSON Schema kayıtlarını runtime’da enforce eder. AsyncAPI spec bu kaydı dokümante eder; ikisi birbirini ikame etmez, tamamlar. Stream processing (Flink, Kafka Streams, Spark) hatlarında AsyncAPI spec’leri topic’in dokümantasyon kaynağı haline gelir; runtime davranışla doküman senkron tutulur.

Open Data Contract Standard (ODCS) ve Veri Ürünü Sözleşmeleri

ODCS, hem tablo (Snowflake, BigQuery, Iceberg, Delta) hem stream (Kafka topic) için kullanılabilen tek YAML sözleşme. Bitol projesinin altında, LF AI & Data Foundation incubation aşamasında; aktif katkı verenler arasında PayPal, Atlan, Adidas Tech, Booking.com mühendislik ekipleri var (proje GitHub commit geçmişinden).

v3.0.0 (Mayıs 2024) ile temel yapı:

• info: contract ID, version, status (draft/active/deprecated), domain, dataProduct.
• schema: logical types + physical types (warehouse-spesifik), primary keys, partition columns.
• quality: SodaCL, Great Expectations veya custom SQL ile assertions. Veri kalitesi araçları bu blokla doğrudan entegre olur.
• servicelevels: availability, retention, freshness, latency, completeness, frequency.
• support: Slack channel, email, MS Teams URL’i.
• roles: data product owner, steward, on-call.

Önemli pratik: ODCS dosyası tek başına bir şey enforce etmez — değeri toolchain’de. datacontract.com CLI (datacontract-cli, MIT lisansı, Python tabanlı), ODCS dosyasını okuyup Soda Core veya Great Expectations testlerini otomatik üretebiliyor; dbt projesine model contract eşleştirebiliyor; OpenAPI ya da AsyncAPI export edebiliyor. Yani ODCS “kaynak gerçek” → CLI “transformer” → çoklu hedef.

Üretim Mimarisi: Üç Katmanlı Contract Stack

Gerçekçi bir üretim setup’ı tek araç değil, üç katmanı birleştirir. Tipik referans mimari Ömer Önal danışmanlık projelerinde son 18 ayda şu örüntüye oturdu:

1. Source of truth katmanı (ODCS YAML): Her veri ürünü için Git repo’sunda contracts//.yaml. PR ile değişiklik, sahiplik CODEOWNERS’tan.
2. Test & doğrulama katmanı: Pact (HTTP consumer-provider), datacontract CLI (data quality tests, Soda/GE), AsyncAPI validator (Kafka topic compatibility).
3. Runtime enforcement katmanı: Confluent/Glue Schema Registry, dbt model contracts, Snowflake tag-based policies, Iceberg schema evolution rules.

Bu mimaride contract değişikliği iş akışı: ODCS YAML PR → CI’da datacontract-cli lint + test → AsyncAPI/OpenAPI auto-generate → Schema Registry’e push → consumer test (Pact verify) → merge. Tipik döngü 15-25 dakika; tüm consumer’lara feedback PR aşamasında geliyor.

Katman	Araç seçenekleri	Tipik aylık maliyet (orta ölçek)	Maturity	Operasyonel yük
Source of truth	ODCS YAML (Git), datacontract.com	Yalnız Git — ~$0 ek	Emerging	Düşük
HTTP contract test	Pact OSS / Pactflow	OSS $0, Pactflow ~$300-$1500	Olgun (10+ yıl)	Orta
Event contract test	AsyncAPI CLI, Pact Message	OSS $0	Olgun	Orta
Veri kalitesi tests	Soda Core/Cloud, Great Expectations	Soda Cloud ~$500-$3000, GE OSS $0	Olgun	Orta-Yüksek
Schema Registry	Confluent SR, AWS Glue SR, Apicurio	Confluent ~$200-$1000, Glue ~$50	Olgun	Düşük
dbt model contracts	dbt Core (v1.5+), dbt Cloud	dbt Cloud ~$100/dev/ay	Yeni (2023+)	Düşük

Orta ölçek (10-15 data engineer, 5-10 domain) için toplam ek maliyet aylık $1500-$5000 bandı, ROI ise schema-related incident maliyetinin yüzde 60-80 düşmesi. dbt analytics engineering ekibi için model contracts adopsiyon eşiği düşük; mevcut dbt projesine YAML eklentisi.

dbt Model Contracts ile Warehouse Tarafı Enforcement

dbt Core v1.5 (Nisan 2023) ile gelen model contracts özelliği, warehouse’a yazılan dbt model çıktısının şema sözleşmesini test eder. contract: {enforced: true} + columns listesinde her alanın data_type ve constraint’lerini (not_null, unique, primary_key, foreign_key, check) tanımlarsın. Build sırasında dbt önce CREATE TABLE’ı geçici yapar; şema uyuşmazsa build fail.

dbt model contract ODCS ile şu şekilde eşlenir: ODCS schema bloğu dbt model’in columns listesine map edilir; ODCS quality bloğu dbt tests’e (built-in + dbt-expectations paketi) dönüşür. datacontract-cli’nin export --format dbt komutu bu çevirimi otomatik yapar.

Constraint	Snowflake	BigQuery	Postgres	Redshift	dbt Core enforcement
not_null	Enforced	Enforced	Enforced	Enforced	Build-time check
unique	Bilgilendirici	Bilgilendirici	Enforced	Bilgilendirici	Test üzerinden
primary_key	Bilgilendirici	Bilgilendirici	Enforced	Bilgilendirici	Test üzerinden
foreign_key	Bilgilendirici	Yok	Enforced	Bilgilendirici	Test üzerinden
check	Bilgilendirici	Yok	Enforced	Bilgilendirici	Test üzerinden

Pratik gözlem: BigQuery vs Snowflake seçimi yapmış ekiplerin çoğunda warehouse-level constraint’ler bilgilendirici olduğu için gerçek enforcement dbt tests’e veya Soda checks’e bırakılır. ODCS quality bloğu burada birleştirici dil görevi görür.

Kafka, Iceberg ve Tablo Format Sözleşmeleri

Event-driven katmanda Confluent Schema Registry (community edition Apache 2.0, Confluent Platform ticari) ile Avro/Protobuf/JSON Schema kayıtlarını compatibility seviyesine bağlı yönetirsin: BACKWARD, FORWARD, FULL, NONE. ODCS dosyasında schema.kind: kafka belirtildiğinde datacontract-cli Schema Registry’den şemayı pull edip karşılaştırır.

Tablo formatları (Apache Iceberg, Delta Lake) son iki yılda hızlandı — Iceberg v2 spec’i 2022, Iceberg v3 spec çalışması 2024’te aktif. Schema evolution rules Iceberg’de tabloya ait metadata’da; add column geriye uyumlu, drop column breaking, type promotion sınırlı (int→long OK, long→int değil). Iceberg Delta Lake açık tablo formatları tarafında contract uygulaması: ODCS dosyası table’ın schema source of truth’u, Iceberg metadata runtime enforcement.

Pratik öneri: yeni bir veri ürünü için contract sırası — (1) ODCS YAML draft, (2) consumer’larla review (Pact-style consumer expectations), (3) Schema Registry / Iceberg metadata oluştur, (4) datacontract CLI ile quality tests generate, (5) dbt model contracts’a senkronla, (6) Slack/Teams alert kanalları bağla.

Performans, Latency ve Operasyonel Metrikler

Contract tooling’in çalışma maliyetini ölçtüm. Aşağıdaki benchmark’lar orta ölçek (50 contract, 200 dbt model, 30 Kafka topic, 8 consumer microservice) bir setup’ta tipik değerleri yansıtır. Rakamlar yaklaşık — donanım, ağ ve toolchain konfigürasyonuna göre değişir.

İşlem	Tool	Tipik latency / süre	CI etkisi	Frekans
Pact consumer test çalıştırma	Pact JVM/JS	~50-200 ms / interaction	PR’da, +2-5 dk total	Her PR
Pact provider verification	Pact CLI	~500 ms – 3 sn / pact	+5-15 dk	Her provider deploy
AsyncAPI spec validation	asyncapi-cli	~200-800 ms	+1 dk	Her PR
datacontract CLI test (Soda)	datacontract-cli	~5-30 sn / contract	+3-10 dk	Nightly + PR
dbt build (contract enforced)	dbt Core	Model başına +50-200 ms overhead	+10-20% build süresi	Her build
Schema Registry compatibility check	Confluent SR	~10-50 ms	Negligible	Her produce
Iceberg schema evolution commit	Iceberg	~100-500 ms	Negligible	Schema değişiminde

Toplam PR turn-around süresinde ortalama 8-15 dakika ek; bunu kabul etmek schema-related production incident maliyetinin yanında düşük fiyat. Veritabanı performans optimizasyonunda olduğu gibi, ölçmeden tahmin yapmamak prensibi data contract pratiğine de uygulanır — her ekibin baseline’ı farklı, ortalama rakamlar yalnızca yön gösterir.

Anti-Pattern’ler ve Yaygın Hatalar

Adopsiyonun başarısız olduğu projelerde tekrar eden örüntüler:

1. Contract’ı producer ekibe dayatmak: Tüketici beklentisi olmadan yazılan contract dokümantasyon olur, test olmaz.
2. Tek araca bağlanmak: Sadece schema registry, sadece Pact veya sadece ODCS — boyutlar farklı, üçü gerekir.
3. Versiyonlama disiplini eksikliği: Breaking change’i minor sürüm olarak yayımlamak, deprecate süresi tanımlamamak.
4. Quality test’i contract’tan ayırmak: Soda checks’i ayrı bir repo’da tutmak — değişiklik senkronu kopar.
5. Bürokrasi-yönelimli kullanım: Her küçük değişiklik için 7 onay zinciri — adoption ölür.
6. Consumer test eksikliği: Sadece provider tarafında lint yapmak, gerçek consumer beklentisini test etmemek.
7. Schema Registry compatibility’i FULL’e zorlamak: Bazı değişiklikler için BACKWARD yeterli; FULL adoption maliyetini şişirir.

Veri yönetişimi (GDPR/KVKK, data catalog) projelerinde contract pratiği regülasyon uyumuyla doğal kesişiyor — PII alanları, retention süreleri ODCS’de açık tanımlanınca KVKK denetim sorularına makine-okunabilir cevap çıkıyor; audit trail için de aynı YAML kaynak görevi görüyor.

Sıkça Sorulan Sorular (SSS)

Sonuç

Data contract 2026’da artık tartışılan değil, uygulanan bir pratik. Üç katmanlı stack — ODCS source of truth, Pact + AsyncAPI test, Schema Registry + dbt + Iceberg runtime enforcement — şu an sektörün convergence noktası. Tek aracı seçip “data contract’ımız var” demek çözüm değil; semantik, kalite, SLA ve sahiplik boyutlarını birlikte tanımlayan, makine-okunabilir ve CI’da test edilen sözleşmeler gerçek değer üretiyor.

Karar çerçevesi: HTTP-ağırlıklı microservice mimariniz varsa Pact ile başlayın; event-driven yapınızda Kafka veya benzeri varsa AsyncAPI + Schema Registry zorunlu; data warehouse/lake katmanınız varsa ODCS + dbt model contracts + Soda/Great Expectations kombinasyonu. Tüm üç katman birden gerekiyorsa ODCS’i source of truth tutup datacontract-cli ile diğer katmanlara senkronize edin.

Adopsiyon roadmap’inde sırasıyla: (1) tek bir kritik veri ürünüyle pilot, (2) tooling stack’ini sabitle, (3) sahiplik ve roles bloğunu domain owner’larla net yaz, (4) CI’a entegre et, (5) deprecate süreci ve consumer feedback kanallarını kur. Mimarinizi modernize ederken contract katmanını bağımsız bir altyapı projesi yerine, mevcut data platform initiative’inizin doğal bir parçası olarak konumlandırmak için iletişim sayfasından ulaşabilirsiniz.

Dış kaynaklar ve standart referansları:

• Open Data Contract Standard (ODCS) — GitHub bitol-io
• AsyncAPI 3.0.0 Specification
• Pact Documentation — pact.io
• Data Contract Specification & CLI
• dbt Model Contracts — dbt Docs
• Confluent Schema Registry Documentation
• Apache Iceberg Table Spec