Data Contracts for Models

A feature row is a set of claims: this value describes this entity, means this business concept, was produced from these sources and transformations, was available by this time, and may be used for this purpose. The storage type says almost none of that. A robust contract makes the claims explicit enough for producers and consumers to test independently.

Use timezone-aware timestamps and define inclusivity, late-arrival policy, and correction behavior. For batch training, construct point-in-time joins using availability, not merely event time. For retrieval, version document validity and index inclusion time so an evaluation cannot retrieve a document that was unavailable at the simulated query time.

The reference artifact defines feature kinds, meanings, finite bounds, entity and time fields, intended and prohibited uses, and lineage sources. It runtime-allowlists feature kinds, rejects unknown fields and non-finite numeric values, treats booleans as distinct from integers, requires timezone-aware timestamps, and checks that feature availability does not cross the decision cutoff. The implementation is deliberately dependency-free so the contract mechanics stay inspectable.

1if __name__ == "__main__":
2    valid_errors = validate_record(
3        SUPPORT_REQUEST_CONTRACT,
4        VALID_RECORD,
5        use="refund-triage",
6        decision_time="2026-08-11T09:00:05Z",
7    )
8    print("valid_record=PASS" if not valid_errors else "valid_record=FAIL")
9 
10    rejected = {**VALID_RECORD, "features_available_at": "2026-08-11T09:00:06Z"}
11    rejected_errors = validate_record(
12        SUPPORT_REQUEST_CONTRACT,
13        rejected,
14        use="automated-refund",
15        decision_time="2026-08-11T09:00:05Z",
16    )
17    print("rejected_record=FAIL" if rejected_errors else "rejected_record=PASS")
18    for validation_error in rejected_errors:
19        print(f"- {validation_error}")

valid_record=PASS
rejected_record=FAIL
- use 'automated-refund' is prohibited
- available_at must not be after decision_time

1. 01Name the entity and grainState what one row represents and the stability rules for its key. Many duplicate and join failures begin with an implicit grain.
2. 02Write feature meaningsInclude unit, population, transformation, missing-value semantics, and any vocabulary or normalization rules.
3. 03Bind timeRecord event and availability clocks, cutoff behavior, late data, correction policy, and label timing.
4. 04Bind lineage and useIdentify source snapshots, transform revisions, responsible owners, intended uses, prohibited uses, and retention requirements.
5. 05Choose failure behaviorReject, quarantine, degrade, or alert explicitly. Silent coercion creates plausible but semantically invalid model inputs.

Contract versioning is a change-management policy, not decoration. A field addition is compatible only if deployed consumers tolerate it; a narrower range is compatible only if existing valid producers already satisfy it; a meaning or unit change is breaking even when name and type stay constant. The reference artifact uses semantic x.y.z notation, but the team must define what major, minor, and patch mean for its producers and consumers.

1. 01Keep the type, change the unitEmit account age in hours under a field documented as days. Range and type checks may pass while model behavior shifts.
2. 02Backfill the futureCorrect historical rows after outcomes are known, then verify that training reconstructs what was available at the original decision cutoff.
3. 03Reuse an identifierMerge records from a source that recycles keys. Test entity namespace and grain before joins create silent collisions.
4. 04Add a helpful fieldSend an unknown feature to a strict consumer and a permissive consumer. Compare whether schema evolution is explicit or silently ignored.
5. 05Change the populationKeep every record valid but route a new country, language, product tier, or acquisition channel. Contract validity and distribution fitness are separate checks.
6. 06Reuse data for another purposeAttempt a prohibited use through the same technically valid pipeline and verify that policy is enforced before consumption.

• Track contract violations separately from distribution drift and model-quality regression; they need different owners and responses.
• Quarantine invalid batches or records with source evidence. Do not repair them invisibly inside the trainer.
• Compare training and serving transformations from shared, versioned definitions while still testing both execution paths.
• Include contract version and source snapshot in experiment manifests, model cards, index manifests, and inference traces.
• Define freshness and late-arrival service objectives from product decisions rather than choosing one universal threshold.
• Coordinate breaking changes with dual-read or dual-write periods, shadow validation, rollback, and removal dates.