Writing a Production-Ready Data Contract with ODCS (Orders Example)

Giriş: Sorun Neden Sözleşmede?

Geçen ay bir e-ticaret projesinde checkout ekibi payment_method kolonuna yeni bir değer ekledi. Kod canlıya çıktı. İki saat sonra üç kritik dbt modeli ve gelir tablosu kırıldı. Neden? Çünkü veri sözleşmesi yoktu.

dataopsphere’da savunduğumuz ilkelerden biri Schema Drift Korumasıdır: veriyi rastlantısal yan ürün olmaktan çıkarıp birinci sınıf ürün yapmazsan, en iyi dbt pipeline’ı bile kırılgandır.

Bu rehberde sitedeki orders-checkout-v1 sözleşmesini alıp üretime hazır, CI/CD’ye bağlı bir şablona dönüştüreceğiz.

1. ODCS Sürümleri: Hangi Format Geçerli?

Open Data Contract Standard (ODCS), Bitol / Linux Foundation projesidir. Sitede iki format ailesi ile karşılaşabilirsiniz:

Format ailesi	Ayırt edici alanlar	Durum
ODCS 0.9.x – 1.0.x	`dataContractSpecification`, `info`, `models` + `fields`	Eski araçlar (datacontract-cli’nin ilk sürümleri)
ODCS v3.0.0	`apiVersion`, `kind`, `schema` + `properties`	dataopsphere sözleşme kataloğunun kullandığı format

Bu sayfadaki şablon v3.0.0 formatındadır ve /contracts kataloğundaki beş sözleşmeyle aynı yapıyı kullanır. Eski araç zinciriniz varsa alan adları farklıdır; sürüm notunda kısa bir eşleme tablosu var.

v3.0.0’ın pratikte getirdiği üç şey:

1
quality ve slaProperties ayrımı netleşti: kalite kuralları *veri içeriğini*, SLA *servis davranışını* tanımlar.
2
servers altında Kafka / S3 / BigQuery tek şemada tanımlanabiliyor.
3
customProperties ile takım bazlı sahiplik ve lineage bağlanabiliyor.

2. Üretime Hazır Şablon: Orders Stream Contract

Bu dosyayı contracts/orders-v1.2.0.yaml olarak projenize ekleyin.

yaml

apiVersion: v3.0.0
kind: DataContract
id: orders-checkout-v1
name: Orders Stream Contract
version: 1.2.0
status: production
domain: E-Commerce / Core Banking

description:
  purpose: Master transaction stream for all completed and refunded orders.
  usage: Downstream payment, revenue analytics, and billing pipelines.

servers:
  - server: production-kafka-cluster
    type: kafka
    host: kafka.production.internal:9092
    format: avro

schema:
  - name: order_event
    description: Primary order transaction model
    properties:
      - name: order_id
        logicalType: string
        physicalType: string
        required: true
        unique: true
        description: Unique UUID generated at checkout initiation

      - name: amount_usd
        logicalType: number
        physicalType: double
        required: true
        description: Net transaction amount in USD
        logicalTypeOptions:
          minimum: 0.01
        quality:
          - name: min_amount_constraint
            type: text
            dimension: accuracy
            description: "Minimum transaction amount is 0.01 USD. Negative or zero values are rejected."

      - name: customer_id
        logicalType: string
        physicalType: string
        required: true
        description: Reference to master customer profile

      - name: payment_method
        logicalType: string
        physicalType: string
        required: true
        description: Payment instrument used at checkout
        quality:
          - name: payment_method_enum
            type: text
            dimension: validity
            description: "Allowed values: CREDIT_CARD, DEBIT_CARD, APPLE_PAY, GOOGLE_PAY, BANK_TRANSFER. Adding a value requires a MINOR version bump."

      - name: status
        logicalType: string
        physicalType: string
        required: true
        description: Order lifecycle state
        quality:
          - name: status_enum
            type: text
            dimension: validity
            description: "Allowed values: PENDING, COMPLETED, FAILED, REFUNDED."

      - name: created_at_utc
        logicalType: date
        physicalType: timestamp
        required: true
        description: Event creation time in UTC

slaProperties:
  - property: latency
    value: 500
    unit: ms
    element: p99
  - property: availability
    value: 99.99
    unit: percent
  - property: freshness
    value: 15
    unit: min

▸Kalite Kapıları Açıklaması

Kural	Karşılık geldiği ilke	Etkisi
`freshness` 15 dk	Veri Tazeliği (İlke 1)	Aşılırsa downstream DAG’ler durur
`completeness` %100	Veri Kalitesi Kuralları (İlke 5)	Null gelirse producer retry’a düşer
`uniqueness` %100	Test kapsama	Duplike olursa idempotent yazma reddeder
`payment_method` enum	Schema Drift Koruması (İlke 3)	Listede olmayan değer CI’da kırılır

3. Karşılıklı Sorumluluk: SemVer Nasıl Çalışır?

Sözleşmenin değeri, iki tarafın da hangi değişikliğin ne zaman kırıcı olduğunu aynı şekilde okumasından gelir.

PATCH (v1.2.1): Açıklama düzeltmesi, kritik olmayan kalite kuralı ekleme. Downstream etkilenmez.
MINOR (v1.3.0): payment_method listesine yeni bir değer eklemek. Geriye dönük uyumlu; downstream ekibe bildirim süresi tanınır.
MAJOR (v2.0.0): amount_usd kolonunu silmek veya tipini değiştirmek. Kırıcı değişiklik; amortisman penceresi ve ikili çalıştırma (dual-run) zorunlu.

PR şablonu ipucu. PR açıklamasına şunu ekleyin:

text

Data Contract Change: [ ] No / [x] Yes
BREAKING CHANGE: evet / hayır
Version Bump: PATCH / MINOR / MAJOR

Kırıcı değişikliklerin dağıtım sırası ayrı bir rehberde: Güvenli Değişiklik & Sürüm Yönetimi.

4. Otomatik Validasyon: Her PR’da ve Her Mesajda

Sözleşme yazmak yetmez; CI’da doğrulamak gerekir. Bunu dbt Slim CI ile aynı iş akışına ekleyin.

yaml

# .github/workflows/data-contract-ci.yml
name: Data Contract CI

on:
  pull_request:
    paths:
      - 'contracts/**'

jobs:
  contract_validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Validate Data Contract
        run: |
          pip install datacontract-cli
          datacontract lint contracts/orders-v1.2.0.yaml

      - name: Check Breaking Changes
        run: |
          # Eski ve yeni sürümü karşılaştır; kırıcı fark varsa job'ı düşür
          datacontract diff contracts/orders-v1.1.0.yaml contracts/orders-v1.2.0.yaml --fail-on breaking

Böylece yazılım ekibi payment_method alanına yeni bir değer eklediğinde CI şunu söyler:

BREAKING? No, but MINOR version bump required. Notify data team.

Bu, Otomatik Validasyon ilkesidir: kontrolü insan dikkatinden alıp pipeline’a taşımak.

Not: datacontract-cli komutları ODCS dosyasının kendi sürümünü okur. v3.0.0 dosyalarında apiVersion/kind alanları bulunmalıdır; 0.9.x formatındaki dosyayı aracın hangi sürümünün desteklediğini kontrol edin.

5. Gözlemlenebilirlik ile Bağlantı

Sözleşme canlıya çıktığında gözlemlenebilirlik katmanı devreye girer. Aşağıdakiler hedef değerlerdir; kendi ortamınızda ölçüp kalibre etmeniz gerekir:

Freshness < 15 dk: Aşılırsa Airflow DAG durur ve kaynak gecikme alarmı üretilir.
Hacim anomalisi: Satır sayısı beklenenin çok altına düşerse alarm tetiklenir.
Schema drift: Schema Registry’de uyumsuz şema gelirse producer bloklanır.
MTTR: Bozulan adımda kontrollü geri alma ve yeniden işleme.

Sonuç: gece 02:00’de kırılan bir panonun yerine, PR aşamasında kırılan bir CI iş akışı.

Kapanış ve Sonraki Adım

Bir sonraki yazıda bu sözleşmeyi Debezium + Kafka + Great Expectations ile canlı validasyon laboratuvarına bağlayacağız: gerçek zamanlı CDC yığınını nasıl ayağa kaldırırız?

bash

docker compose -f templates/streaming/docker-compose.yml up -d
# Kafka-UI: http://localhost:8085

İlgili sayfalar:

Data Contracts Kataloğu — beş domain sözleşmesi ve ODCS örnekleri
Güvenli Değişiklik & Sürüm Yönetimi — Expand & Contract geçiş protokolü
Veri Kalitesi Hatasına Müdahale — ihlal, karantina ve idempotent yeniden işleme
DataOps Sözlüğü — veri sözleşmesi terimi

Kaynaklar

ODCS ile Üretime Hazır Veri Sözleşmesi Nasıl Yazılır? (Orders Örneği)