Data contracts, ownership, and lineage
A trustworthy dataset explains meaning, accountability, and ancestry—not just columns.
Fraud labels arrive late and online features disagree with training data.
This chapter moves from declare grain and semantics to record lineage edges. 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.
Connect source snapshot to transformation version, feature set, training run, artifact, and deployment in machine-readable metadata.
Verify the behavior illustrated in account_features.contract.yaml, then measure decision utility, slice reliability, and system latency.
Joining only on customer ID attaches the present balance to every historical row. An unsafe release must degrade to a named baseline or the last known-good version.
Build the idea one layer at a time.
A feature table is a promise passed between teams. Its usefulness depends on knowing what each value means, who repairs it, and where it came from.
Physical schema catches missing columns and wrong types; semantic contracts cover units, entity grain, event meaning, freshness, and invariants. A float column can remain a float while changing from dollars to cents, so type checks alone are not enough.
Ownership turns detection into recovery, and lineage narrows the blast radius. When a producer changes, consumers should be able to trace which feature versions, training snapshots, runs, and deployed models depend on it.
- semantic contracts
- event time
- availability time
- as-of joins
Follow the reasoning before touching the code.
- 01
Declare grain and semantics
State what one row represents, the entity key, time semantics, units, null meaning, ranges, and freshness objective.
- 02
Attach accountable owners
Name a producing owner, consuming owner, escalation path, and compatibility policy for every contract version.
- 03
Record lineage edges
Connect source snapshot to transformation version, feature set, training run, artifact, and deployment in machine-readable metadata.
version: 3
owner: [email protected]
grain: one row per account_id and event_time
primary_key: [account_id, event_time]
freshness:
maximum_lag_minutes: 15
fields:
account_id: {type: string, nullable: false}
event_time:
type: timestamp_utc
nullable: false
balance_usd:
type: float64
unit: USD
minimum: -10000
nullable: false
source: ledger.transactions.v5A compact semantic contract for one feature view.
What to notice
- Grain and primary key make duplicate meaning testable instead of merely checking that account_id exists.
- The balance field records currency and range, allowing a cents migration to be treated as incompatible.
YOUR TURN Pause and predict before revealing the answer.
A producer wants to reinterpret null balance as zero without changing the type. Is this contract-compatible?
Need a hint?
Null meaning is part of semantics even when the physical schema is unchanged.
Check your reasoning
No. It changes consumer behavior and feature distributions; publish a new contract version and migrate dependents explicitly.
Engineering foundations, Evaluation
Connect the chapter to the course’s quantitative spine.
A trustworthy dataset explains meaning, accountability, and ancestry—not just columns. The feature availability invariant 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.
Feature availability invariant
| Symbol | Meaning / shape / unit |
|---|---|
t_available | time the value became knowable |
t_decision | prediction cutoff |
f_i | feature i |
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: t_available, t_decision, f_i.
- 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_c03(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 trustworthy dataset explains meaning, accountability, and ancestry—not just columns. The path below shows where that reasoning needs an artifact, a test, an owner, or a fallback.
- 01
Turn “Declare grain and semantics” into a written invariant and a failing test.
- 02
Promote account_features.contract.yaml from illustration to a versioned implementation with representative fixtures.
- 03
Use “Record lineage edges” as the release checkpoint: Connect source snapshot to transformation version, feature set, training run, artifact, and deployment in machine-readable metadata.
- 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
Joining only on customer ID attaches the present balance to every historical row. 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.
Point-in-time feature system
Design a versioned training set and online lookup from transaction, account, and outcome events.
- Contracts and lineage
- Temporal join specification
- Late-event/backfill policy
- Offline-online parity report
Read primary material with a purpose.
Return to the opening failure.
Version contracts, temporal joins, transform state, snapshots, backfills, and continuous offline/online parity checks.
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 data contracts, point-in-time features, backfills, quality gates, and lineage.