Data contracts, ownership, lineage, and quality
A data contract is a shared operational promise about meaning, time, quality, and response—not a list of column types.
A late feature silently corrupts every downstream prediction.
This chapter moves from write semantic promises to attach lineage to releases. We will make the idea concrete in a small code example before placing it back inside a production system with a declared latency, cost, and operator-capacity budget.
Persist source and transform identities with training sets, feature materializations, models, and predictions.
Verify the behavior illustrated in transactions.contract.yaml, then measure decision utility, slice reliability, and system latency.
A backfill uses corrected future knowledge and silently inflates offline AUC. An unsafe release must degrade to a named baseline or the last known-good version.
Build the idea one layer at a time.
A table can keep the same columns while its meaning quietly changes. A production data contract protects semantics as well as types: who owns the data, when it becomes available, what each value means, how quality is measured, and which consumers are at risk.
Schema validation catches a missing column or incompatible type, but it cannot infer that cents became dollars or that a status is now written before human review. Contracts add units, keys, null rules, freshness, event and availability time, acceptable ranges, and compatibility policy. Ownership turns a failed check into an actionable incident rather than an orphaned alert.
Lineage connects a prediction back through features, source snapshots, transformations, and code. Quality rules should sit at meaningful boundaries: producer checks protect source truth, transformation checks protect derived invariants, and consumer checks protect the assumptions a model actually uses.
- Kafka
- Flink/Spark
- Parquet/lakehouse
- watermarks
Follow the reasoning before touching the code.
- 01
Write semantic promises
For each field, state meaning, unit, key, temporal semantics, null behavior, and allowed evolution—not only its storage type.
- 02
Assign boundaries and owners
Name who detects, triages, fixes, approves exceptions, and communicates blast radius for each contract.
- 03
Attach lineage to releases
Persist source and transform identities with training sets, feature materializations, models, and predictions.
dataset: transactions
owner: [email protected]
primary_key: [transaction_id]
fields:
amount_cents:
type: integer
minimum: 0
unit: USD_cents
available_at:
type: timestamp
freshness: 15m
on_incompatible_change: quarantineA compact contract carries semantics and response ownership
What to notice
- The unit makes a physically valid but semantically wrong dollars-to-cents change detectable in review and tests.
- Quarantine is an explicit behavior; silent coercion would let corrupted rows spread to every downstream artifact.
YOUR TURN Pause and predict before revealing the answer.
A producer begins sending refunds as negative amount_cents. Which parts of the contract and system must change before accepting it?
Need a hint?
Consider range, semantic meaning, downstream aggregates, compatibility, and ownership.
Check your reasoning
Revise the amount semantics and minimum, version the contract, test every consumer that assumed nonnegative purchases, backfill deliberately, and obtain producer and consumer approval before promotion.
Data & features, GPU training
Connect the chapter to the course’s quantitative spine.
A data contract is a shared operational promise about meaning, time, quality, and response—not a list of column types. The point-in-time feature lookup below is the shared course-level lens that helps quantify the surrounding system. Name each symbol, check its units or shape, and use only values that were available at the production cutoff.
Point-in-time feature lookup
| Symbol | Meaning / shape / unit |
|---|---|
j | entity |
t_p | historical prediction time |
e | eligible event |
Open derivation and numerical substitution
Start from the production quantity being optimized, substitute the observed values with their declared units, then isolate the model-controlled term. Preserve shape annotations at each step so broadcasting or aggregation cannot silently change the result.
- Write the named inputs: j, t_p, e.
- Substitute one small, hand-checkable batch before vectorizing.
- Calculate an independent reference value and compare within a declared tolerance.
# equation → code contract
inputs = validate_shapes_and_units(batch)
value = compute_c17(inputs)
assert is_finite(value)Change one assumption and make the tradeoff visible.
Use the worked chapter as your prediction, then change one input in the lab and explain why the output moves. The lab runs predefined TypeScript and never executes learner code, so the focus stays on the concept rather than setup.
Point-in-time freshness lab
Delay feature arrival and see which historical rows remain eligible.
Assumption: Five events have fixed prediction cutoffs separated by six hours.
Open nonvisual data table
| Item | Computed state | Interpretation |
|---|---|---|
| row 1 | cutoff +0h | not yet knowable |
| row 2 | cutoff +6h | eligible |
| row 3 | cutoff +12h | eligible |
| row 4 | cutoff +18h | eligible |
| row 5 | cutoff +24h | eligible |
Trace the complete operating path.
Carry the chapter’s central idea into the system: A data contract is a shared operational promise about meaning, time, quality, and response—not a list of column types. The path below shows where that reasoning needs an artifact, a test, an owner, or a fallback.
- 01
Turn “Write semantic promises” into a written invariant and a failing test.
- 02
Promote transactions.contract.yaml from illustration to a versioned implementation with representative fixtures.
- 03
Use “Attach lineage to releases” as the release checkpoint: Persist source and transform identities with training sets, feature materializations, models, and predictions.
- 04
Serve or materialize behind explicit a declared latency, cost, and operator-capacity budget.
- 05
Join telemetry to mature outcomes and retain a rollback path.
Observability
Join service health, input quality, prediction distributions, slice behavior, and mature outcomes by exact version.
Cost
Measure storage, preprocessing, compute, queueing, and human review under a representative arrival pattern.
Failure modes
A backfill uses corrected future knowledge and silently inflates offline AUC. Add a detector, owner, mitigation, and stop condition for this class of failure.
Alternatives
Compare a rule, a simpler statistical baseline, and a different system boundary before adding model complexity.
Explain the contract, not just the vocabulary.
Local mini ML platform
Specify idempotent events, a point-in-time join, shared feature definition, quality gates, lineage, and model registration.
- Data contract
- Late-event semantics
- Feature parity design
- Lineage/registry record
Read primary material with a purpose.
Return to the opening failure.
Make temporal correctness, ownership, lineage, reproducibility, and escape hatches the platform defaults.
For this lesson, the release evidence is the worked code example, a hand-checked formal result, deterministic simulation output, a ≥80% checkpoint, the production rubric, and a named fallback. The course resolves when the system can produce a traced batch/stream platform with orchestration, registry, lineage, and ownership.