Model Input / Output Contract¶

Interface contract — instantiates Dimensional Consistency Check

A written specification pinning the unit, dimension, scale basis, and valid range of every model input and output, so an upstream change cannot silently corrupt a downstream result.

Model Input / Output Contract is the standing agreement that fixes, in advance and in writing, what every field flowing into and out of a model is: its unit, its dimension, its scale basis, its meaning, and the range it is allowed to take. Its defining feature is that it is a contract, not a check — a durable interface specification that other components and pipelines are held to, so consistency is enforced continuously at the boundary rather than re-verified by hand each run. Its whole reason for existing is the silent-corruption failure: an upstream data source changes a unit, a denominator, or a definition, nothing throws an error, and a downstream model keeps producing confident, wrong numbers. The contract turns that silent drift into a loud, early violation.

Example¶

A demand-forecasting model at a retailer ingests a "temperature" feature and a "sales" feature from upstream data pipelines. The contract specifies each: temperature in degrees Celsius, range −30 to 50; sales as units-per-store-per-day, a flow, non-negative. Months later a vendor migration switches the weather feed to Fahrenheit. No code breaks — 68 is a perfectly valid number — but it is now interpreted as 68°C.^[1] The contract catches it immediately: 68 sits outside the declared −30-to-50 range, so the input is rejected at the boundary before it reaches the model, and the alert points straight at the feed that changed rather than at a mysterious forecast drift discovered weeks later.

The contract also fixes the reference standard the pipeline conforms to (Celsius, not "whatever the vendor sends") and names the transfer boundary: this model was fit on one chain's stores, and the contract states that porting it to a new region requires re-validating the ranges, not assuming they carry. What would otherwise be tacit knowledge in one analyst's head becomes an enforced interface.

How it works¶

Specify every field. For each input and output, declare unit, dimension, scale basis, meaning, and the valid range — the canonical definition the pipeline must meet.
Enforce at the boundary. Values are validated against the contract on the way in and out; a violation is rejected or alerted rather than silently consumed.
Range-check to catch unit swaps. A declared plausible range turns an invisible unit change into an out-of-bounds value, because the wrong unit usually lands the number outside its expected span.
State where the contract holds. The specification names the population, region, or regime it was validated for, so moving the model triggers re-validation instead of silent reuse.

Tuning parameters¶

Range tightness — how narrow the valid bands are. Tight ranges catch subtle unit and scale errors but reject legitimate outliers; loose ranges only catch gross swaps.
Enforcement stance — whether a violation hard-fails the pipeline or merely warns. Hard failure is safest for critical models; warnings suit exploratory ones.
Field coverage — every intermediate field under contract, or only the external inputs and outputs. Fuller coverage catches internal drift at more maintenance cost.
Versioning discipline — whether the contract is version-controlled and diffed on change, so definition edits are as visible as code edits.

When it helps, and when it misleads¶

Its strength is durability: it protects a model over time and across handoffs, converting the silent-corruption failure mode — the most dangerous one for long-lived models — into an immediate, well-located error. It is the mechanism of choice wherever a model outlives the people who built it or consumes data it does not control.

Its weakness is maintenance. A contract that is not updated when the model legitimately changes becomes a source of false rejections, and teams learn to bypass a contract that cries wolf. It also guards only what it declares — a construct-level meaning shift that stays inside the declared range slips through. The discipline is to keep the contract versioned alongside the model, treat every range as a claim to be revisited, and pair it with a meaning check for constructs that can drift without leaving their numeric band.

How it implements the components¶

unit_dimension_map — the contract is a persisted unit/dimension map, one entry per field, made enforceable rather than advisory.
reference_standard — it names the canonical unit, basis, and definition each field must conform to, the standard the pipeline is held against.
transfer_boundary — it states the population and regime the model was validated for, so reuse elsewhere triggers re-validation.
tolerance_threshold — the declared valid range for each field is the tolerance whose breach raises the alarm.

It does not resolve a violation once raised (conversion belongs to Unit Conversion Workflow) nor decide the meaning of money-like constructs (that is Finance / Accounting Unit Check); it specifies and enforces the interface.

Instantiates: Dimensional Consistency Check — the archetype frozen into a durable, enforced interface rather than a one-time review.
Consumes: Unit Conversion Workflow is what a producer runs to meet the contract when its native units differ.
Sibling mechanisms: Unit Conversion Workflow · Cross-Scale Transfer Review · Dimensional Analysis Table · Dimensionless Ratio Construction · Engineering Equation Sanity Check · Finance / Accounting Unit Check · Normalized Metric Design · Per-Capita or Per-Unit Conversion · Spreadsheet Unit Audit · Stock / Flow Separation Check · Unit Check

References¶

[1] The pattern generalizes design by contract — Bertrand Meyer's principle that a software component should carry explicit, checkable preconditions and postconditions — to the units and dimensions of the data crossing a model's boundary. ↩