Advanced

Data Contracts & Schema Evolution in Production

Mencegah breaking change antar producer-consumer data dengan kontrak yang jelas

45 min read Updated Mar 2026 By DataLearn Team

Mode Baca Pemula

Anggap data contract sebagai "API spec untuk data". Fokus baca:

Apa yang dijanjikan producer ke consumer
Apa dampaknya kalau schema berubah tanpa aturan
Bagaimana rollout perubahan tanpa mematahkan pipeline lama

Kamus istilah: DE-GLOSSARY.md

Prasyarat Ringan

Paham alur producer -> pipeline -> consumer
Tahu schema data itu bisa berubah dari waktu ke waktu
Pernah melihat incident karena field hilang/berubah tipe

Istilah Penting (3 Lapis)

Istilah: Data Contract

Definisi awam: Janji format data agar pengirim dan penerima tidak salah paham.

Definisi teknis: Spesifikasi skema, semantik, SLA, dan versioning antara data producer dan consumer.

Contoh praktis: event_time wajib ISO timestamp UTC, order_id wajib string non-null.

Istilah: Backward Compatibility

Definisi awam: Versi baru masih bisa dipakai oleh sistem lama.

Definisi teknis: Perubahan schema yang tidak mematahkan consumer yang masih memakai versi sebelumnya.

Contoh praktis: Menambah kolom opsional tanpa menghapus kolom lama.

Problem Bisnis yang Paling Sering

            Tanpa Contract: "Works in Dev, Breaks in Production"
            Producer ubah tipe data diam-diam (price: string -> float).
Consumer gagal parsing dan dashboard kosong.
MTTR tinggi karena tidak ada owner perubahan schema.

        

Komponen Wajib dalam Data Contract

Komponen	Isi Minimum	Kenapa Penting
Schema	Nama field, tipe, nullable, default	Mencegah parsing error
Semantics	Arti bisnis per field	Mencegah metric drift
Quality Rules	Range, uniqueness, referential checks	Deteksi anomali lebih dini
SLA/SLO	Freshness, completeness, availability	Ekspektasi layanan jelas
Versioning Policy	Major/minor changes + deprecation window	Perubahan aman lintas tim
Ownership	Producer owner, consumer owner, escalation	Incident response cepat

Schema Evolution Rules (Yang Aman)

Perubahan	Compatibility	Rekomendasi
Tambah field opsional	Umumnya aman (backward)	Boleh langsung, tetap umumkan change log
Hapus field lama	Berisiko tinggi	Deprecation minimum 1-2 release cycle
Ubah tipe field	Sering breaking	Buat field baru, migrasi bertahap
Ubah makna field	Silent breaking change	Wajib major version + komunikasi lintas tim

Decision Framework: Strict vs Flexible Contract

Kondisi	Pilih Strict	Pilih Flexible
Domain finansial, compliance tinggi	Ya, wajib gate di CI + schema registry	Tidak direkomendasikan
Eksperimen produk cepat	Hanya untuk field kritikal	Ya, dengan guardrail minimum
Banyak consumer lintas tim	Ya, kontrak formal + deprecation policy	Berisiko tinggi

Implementation Walkthrough

1) Definisikan Contract Spec

# contract/order_events.v2.yaml
name: order_events
version: 2.1.0
owner: data-platform@company.com
sla:
  freshness_minutes: 15
  completeness_min: 0.995
schema:
  - name: order_id
    type: string
    nullable: false
  - name: event_time
    type: timestamp
    nullable: false
  - name: gross_amount
    type: decimal(18,2)
    nullable: false
  - name: discount_amount
    type: decimal(18,2)
    nullable: true
        

2) Tambahkan Contract Check di CI

# Pseudo CI step
if schema_change_is_breaking(new_schema, old_schema):
    fail_build("Breaking change detected. Create major version + migration plan")
        

3) Rollout Perubahan dengan Deprecation Window

Release versi baru kontrak (misal v2.1) dengan changelog.
Jalankan dual-write jika perlu (field lama + field baru).
Monitor adoption consumer selama window deprecation.
Hapus field lama setelah semua consumer migrasi.

Failure Modes & Anti-Patterns

            Anti-Patterns yang Sering Terjadi
            Schema by accident: schema berubah karena refactor tanpa review data.
No owner: saat incident, tidak jelas siapa approve perubahan.
No deprecation policy: field dihapus mendadak.
Contract only on paper: tidak ada enforcement di pipeline/CI.
Semantics drift: nama field sama, arti bisnis berubah.

        

Production Readiness Checklist

            Checklist Sebelum Contract Live
            Contract spec punya owner, version, dan changelog.
Schema validation jalan otomatis di CI/CD.
Compatibility policy didokumentasikan (backward/forward).
Deprecation window dan komunikasi lintas tim sudah jelas.
SLA/SLO freshness dan completeness sudah disepakati.
Alert untuk contract violation sudah aktif.
Runbook incident contract breach tersedia.

        

Exercise: Rancang Data Contract untuk Event Checkout

Buat contract untuk event checkout_completed dengan syarat:

Dipakai 3 consumer: BI, fraud detection, finance reconciliation.
Freshness maksimal 10 menit.
Perubahan schema harus backward-compatible.

Deliverable:

Draft contract spec (field + type + nullable + semantic notes).
Versioning policy (major/minor rules).
Migration plan jika gross_amount dipecah jadi net/tax/fee.

Quick Quiz

1. Perubahan mana yang paling berisiko breaking?

A. Menambah field opsional

B. Menambah deskripsi dokumentasi

C. Mengubah tipe field yang sudah dipakai consumer

D. Menambah owner metadata

2. Tujuan utama deprecation window adalah?

A. Menambah kompleksitas release

B. Memberi waktu consumer migrasi tanpa downtime

C. Menghilangkan kebutuhan komunikasi

D. Mengurangi kebutuhan testing