The proposition before the prediction

Data pipelines usually make values visible before they make propositions explicit. A table shows income_amount = 72000. An API returns status = active. A document index stores a policy sentence. The downstream system can move these values through parsers, tensors and prompts. It still does not know enough to act.

A consequential consumer needs at least the value, unit, entity grain, scope, valid time, recording time, source authority and transformation history. The useful object is therefore closer to a proposition:

Here, value is the encoded observation; meaning includes unit and business definition; subject identifies what the observation concerns; scope limits where it applies; valid time says when it holds in the represented world; recorded time says when the system knew it; and provenance identifies the source and transformations. Change any one component and the same bytes may assert something else.

A data defect is often a proposition defect before it is a numerical defect. Null checks and range checks find some failures. They do not find a change from booked balance to available balance, household income to individual income, event time to ingestion time, or approved policy to draft policy when the representation remains compatible.

Thought experiment one: the same double

Imagine two pipelines that differ in only one causal feature. Both emit the IEEE floating-point value 6000.0. Both use the field name income_amount. Both arrive within a second and satisfy the same model signature.

In pipeline A, the value means annual gross income in pounds. In pipeline B, it means monthly net income in pounds. A model trained on annual gross values does not receive the distinction because the tensor contains only 6000.0. If it proposes a loan decision, its output may be internally consistent with pipeline A while being operationally inappropriate for pipeline B.

Now restore the distinction as contracted metadata and enforce it before tensorisation. Pipeline A passes. Pipeline B either transforms under an approved, versioned rule or stops. The model has not become more intelligent. The system has stopped asking it to infer a hidden data agreement from a number.

Why compatibility stops early

Interface technologies are designed to answer narrower questions. JSON Schema can describe and validate JSON structure and values. Apache Avro defines writer and reader schemas plus resolution rules. Model-serving systems likewise use signatures or inference protocols to state expected names, datatypes, shapes, parameters and outputs, as shown by MLflow model signatures and the KServe V2 protocol.

These mechanisms are valuable. They catch incompatible records before a model sees them. The mistake is to treat their success as evidence that the business proposition is unchanged. Avro's parsing canonical form, for example, removes attributes such as doc because they do not affect how readers parse serialized data. That is sensible for wire compatibility. It also illustrates the boundary: a documentation change can be irrelevant to parsing while being crucial to human meaning.

A model signature has the same limitation. It can require a numerical input called income_amount. It cannot establish whether the amount is individual or household, verified or self-reported, annual or monthly, gross or net, current or historical. Adding these fields to the signature makes them available, but it does not create agreement, ownership, thresholds or a safe response when they violate expectations.

Shape tells the consumer how to read a value; a data contract tells the consumer when that reading is authorised. The contract therefore spans the producer-consumer relationship, not merely the serialisation format.

Why robustness cannot repair a hidden redefinition

Models can be trained to tolerate noise, missingness and bounded distribution shift. That defence applies when the training and operating task still share enough meaning. A systematic change from annual to monthly income is not ordinary noise around the same variable. It replaces the variable while preserving its container.

End-to-end evaluation can eventually expose the harm. A decline rate may move, a calibration curve may degrade, or human reviewers may disagree. Detection at the output, however, leaves many candidate causes: the source, transformation, feature code, model, threshold, policy or population. The later the defect is found, the more decisions it may have touched and the harder attribution becomes.

Research on ML systems has repeatedly warned about this wider boundary. Hidden Technical Debt in Machine Learning Systems identifies undeclared consumers, data dependencies and external changes as sources of system debt. Data Validation for Machine Learning treats input data as a production asset and describes validation for anomalies and train-serving skew. A study of 53 AI practitioners characterised data cascades as compounding downstream effects of upstream data problems.

These findings do not prove that every defect requires a formal contract. They support a narrower engineering conclusion: when a model consumes changing enterprise data, upstream assumptions must become testable at the point where responsibility can still be assigned.

The asymmetry of reconstruction

The causal problem can be stated without any particular data technology. Several upstream worlds can produce the same downstream representation. The number 6000.0 can encode annual income, monthly income, a converted currency, a capped value or a transcription error. Once period, unit, subject and source are removed, the mapping from proposition to tensor is many-to-one.

A downstream model may guess the missing meaning from surrounding records. That guess can be statistically useful, but it is not an authoritative reconstruction. A batch dominated by annual values can make monthly values look like outliers; a new population can reverse the pattern. The model is then asked to infer both the evidence and the decision from the same ambiguous signal.

The contract restores information before that lossy step. It does not make the representation infinitely rich. It preserves the distinctions that the consumer has declared material. Once a material distinction has been erased upstream, no downstream behavioural guarantee can reliably put it back. This irreversibility is why the data boundary precedes the model boundary.

Anatomy of an executable data contract

A data contract is sometimes reduced to a schema file. At the other extreme it becomes a long governance document that no running system can evaluate. Neither form is sufficient for a consequential model consumer. The useful contract joins a human agreement to machine-enforced checks and a change process.

Datasheets for Datasets proposed documentation covering motivation, composition, collection and recommended uses. That work helps people reason about datasets before reuse. The Open Data Contract Standard offers a machine-readable structure spanning schema, quality, service levels, roles and related terms. These are complementary ideas. Documentation makes assumptions inspectable; executable clauses decide whether a particular record or release may cross a particular boundary.

The contract is not the file. It is the producer-consumer promise, its tests, its version policy and the evidence that those tests ran. Six clauses usually carry the burden.

1. Identity, grain and scope

The contract must name the entity and the row's unit of observation. “One row per customer” is different from one row per account, household, application, relationship or customer-day. A join can preserve every datatype while duplicating the grain. A model then sees repeated evidence and may treat it as independent support.

Scope states which population and decision the product supports. A source verified for salaried income may not support self-employment. A product holding current balances may not support historical reconstruction. Scope prevents successful transport from becoming unauthorised reuse.

2. Structure and encoding

This is the familiar layer: field names, types, nullability, cardinality, nested structure, categorical domains and encoding rules. It should use standard validators where possible. A duplicate bespoke type system creates another compatibility problem.

Structural checks are still important even when semantics dominate the argument. A contract that cannot reliably parse a record cannot evaluate its meaning. The ordering inside the gate is therefore pragmatic: parse first, then test the proposition.

3. Meaning, unit and transformation

Every material field needs a definition precise enough to distinguish plausible alternatives. “Income” is too broad. “Verified annual gross employment income before tax and deductions, expressed in GBP for the named applicant” is testable against period, basis, currency, source and subject fields.

Derived fields need transformation identity. An affordability ratio without its numerator, denominator, cut-off dates and code version is not reproducible evidence. The contract does not need to embed an entire code repository. It needs a stable reference to the logic that produced the value and the dependencies that would invalidate it.

4. Quality and reconciliation

Quality is fitness for a declared use, not a generic score. ISO/IEC 25012 provides a general data-quality model, but an operating contract must translate dimensions into decision-specific rules. Ninety-nine per cent completeness may be excellent for exploration and unacceptable if the missing one per cent is the field that determines legal eligibility.

Useful checks include required-field completeness, ranges, uniqueness, referential integrity, distribution expectations, cross-field consistency and reconciliation to an authoritative total. Each failure needs a severity and a disposition. Logging a violation while continuing silently is monitoring, not enforcement.

5. Temporal status and correction

A field named updated_at rarely answers the full temporal question. The contract should distinguish when a fact held in the world, when the system recorded it, when the consumer retrieved it and when the decision used it. Late arrival, back-dated validity and corrections require at least valid-time and transaction-time semantics.

Classic temporal-database work defines valid time as when a fact is true in the represented reality and transaction time as when it is present in the database. Keeping both supports bitemporal questions such as, “What did the system know on Tuesday about what was valid on Monday?” The data contract must also state freshness thresholds, clock tolerance, late-arrival behaviour and whether a correction replaces, amends or invalidates a prior assertion.

6. Authority, lineage, change and failure

The contract names the producer, consumer and steward. It identifies permitted source systems, transformation versions and source record references. OpenLineage supplies a general model for jobs, runs, datasets and extensible facets. Lineage can show where a record travelled; the contract states whether that path and source are permitted for this decision.

Change policy is part of the semantics. A new nullable field may be compatible. A change in unit, grain, definition, source authority or temporal role is breaking even when no parser fails. The contract should state which changes require a new major version, consumer acceptance, parallel validation or rollback.

Finally, failure behaviour must be explicit. The useful choices are not only pass and fail. A low-consequence analytical view might accept a qualified record with a visible caveat. A live payment instruction may need to block on stale state. Other cases require quarantine, repair or human escalation. Admissibility is a decision, not a dashboard colour.

Turn each promise into a proof obligation

A contract clause is strongest when it has four parts: a claim, a test, evidence and a disposition. “Income is annual gross GBP” is the claim. Allowed period, basis and currency values form the mechanical test. The cited payroll record and transformation reference provide evidence. Blocking or re-verification supplies the disposition.

This form prevents two common failures. The first is a threshold without a reason, such as rejecting values older than fifteen minutes without naming the decision that requires that limit. The second is a definition without an observable test, such as calling a field “trusted” while omitting source identity and reconciliation. The four-part clause lets reviewers challenge both the business premise and its implementation.

It also supports controlled exceptions. An authorised reviewer can accept a bounded deviation only by naming the failed claim, evidence considered, permitted scope and expiry. The exception becomes another governed event rather than an invisible override that teaches future operators to ignore the gate.

Thought experiment two: three clocks, one balance

Hold the account balance constant at £10,000 and vary only time.

In case A, the balance was valid at 09:55, recorded at 09:56 and retrieved for a 10:00 decision. In case B, the same balance was valid yesterday, recorded yesterday and retrieved at 10:00. In case C, a correction recorded at 10:05 states that the balance used at 10:00 was wrong at the time.

A model receiving only balance = 10000 sees identical evidence. A timestamp named updated_at may still be ambiguous. The cases require different answers: current admissible state, stale state, and historical decision evidence later corrected.

The contract turns the difference into fields and rules. observed_at carries the source-world observation. recorded_at carries system knowledge. The gate evaluates freshness against decision_at or retrieval time. A correction creates a new assertion linked to the earlier one instead of overwriting history.

Freshness is not a property of a row in isolation. It is a promise between a proposition, a source, a decision and a time. Fifteen minutes may be acceptable for verified income and impossible for an account hold. The contract names the threshold and the safe stale behaviour.

flowchart TD
  A["The number that passed every<br/>model check"] --> B["The proposition before the<br/>prediction"]
  B --> C["Anatomy of an executable data<br/>contract"]
  C --> D["Contracts as executable<br/>operating evidence"]
  D -. "re-test" .-> A
  classDef first fill:#0a1424,stroke:#D95545,stroke-width:2px,color:#e6f3ff
  classDef step fill:#0a1424,stroke:#3f7da0,stroke-width:1px,color:#e6f3ff
  class A first
  class B,C,D step

Contracts as executable operating evidence

A contract earns its place in an AI system when it changes runtime behaviour and leaves evidence. A prose definition without enforcement is useful documentation. A validator without definitions is a collection of unexplained thresholds. The operating instrument combines both and emits a contract receipt.

A receipt should identify the contract and version, evaluated time, source record, transformation version, checks run, failures, verdict and evidence references. It need not contain private source content. Its purpose is to let an operator answer, “Why was this record admitted, qualified or blocked?” and to replay that answer under the same contract.

Five verdicts cover most operating needs:

• Pass: the declared conditions hold and the record may enter the intended context.
• Qualify: the record may support a bounded, low-consequence use with an explicit limitation.
• Quarantine: preserve the record for investigation without exposing it to the consumer.
• Block: deny use because a mandatory condition failed.
• Escalate: route an unresolved conflict or exception to accountable human judgement.

The verdict belongs to the specific use. A stale address can be qualified for meeting preparation and blocked for a legally required notice. The same source record can therefore receive different receipts under different consumer contracts without contradiction.

Worked example one: a minimal income gate

The companion laboratory defines a source-to-consumer contract for one verified annual gross income observation. The required grain is one applicant per payroll observation. The amount must be non-negative annual gross GBP. The observation must be no more than fifteen minutes old, recording lag must stay within five minutes, and the source must be the approved payroll-verification system.

The downstream model signature is deliberately narrow. It accepts an applicant identifier and a numerical income amount. That is enough to illustrate the fault line. Five synthetic records pass the model signature: one valid record, one monthly-net record, one stale record, one unapproved-source record and one record missing a source identifier.

The data contract admits only the valid record. Four defects are therefore invisible to the model signature. In the semantic case, treating £6,000 monthly income as £6,000 annual income changes the synthetic loan-to-income ratio by a factor of twelve. The contract blocks the record before the calculation can masquerade as a model judgement.

Worked example two: a production-shaped credit evidence packet

Consider a synthetic credit-preparation workflow. It reads an applicant profile from customer records, verified income from a payroll provider, liabilities from a bureau, account behaviour from a banking core and policy thresholds from an approved policy service. A language model drafts an evidence summary and a risk model proposes a score. A deterministic policy layer and an accountable reviewer retain decision authority.

Without source contracts, the workflow might join the latest available row from each system and label the result “current customer context”. That phrase hides several assumptions. “Latest” could mean last ingested, last observed, last approved or currently effective. Customer identifiers may be scoped differently. Bureau liabilities may be individual while the application is joint. Policy version 8 may be published but not yet effective.

With contracts, each producer emits or supports a typed evidence envelope. The income contract states annual gross GBP, individual applicant grain, verification source, observation time and freshness. The bureau contract states liability coverage, joint-account treatment, report time and correction rules. The policy contract states publication, approval and effective intervals. Transformations carry version references and reconciliation results.

A context compiler admits only envelopes whose receipts support the requested decision frame. The model sees the claim plus its bounded evidence, not an unqualified extract. If income is stale, the system can request re-verification. If the bureau record is individual but the case requires household exposure, the system can mark the evidence insufficient rather than asking the model to bridge the missing scope.

The model contract now starts at a cleaner boundary. It can specify expected evidence classes, supported missingness, output schema, calibration requirements, abstention and prohibited actions. When the final proposal is wrong, the trace can distinguish an admitted-data failure from a model-behaviour failure or a decision-policy failure.

This separation does not eliminate integration work. It changes its shape. Producers own assertions and change notices. Consumers own decision fitness and failure behaviour. Platform teams provide contract registries, validators, lineage and receipts. Domain stewards arbitrate contested definitions. Model owners stop becoming the default owners of every upstream ambiguity.

Four fault classes become testable

The receipt enables a useful diagnostic split. A source fault occurs when the producer assertion violates the promised meaning, time, quality or authority. A transformation fault occurs when an admitted source is joined, aggregated or converted incorrectly. A model fault occurs when admissible evidence still yields an unacceptable proposal. A decision fault occurs when policy, authority or execution mishandles an otherwise traceable proposal.

The classes are not perfectly independent. A model may amplify a small source error, and a policy threshold may be brittle to a valid population shift. The purpose is not to force every incident into one box. It is to preserve enough operating evidence to test competing explanations instead of treating the final model output as the only observable.

Good data contracts do not protect models from accountability. They remove upstream ambiguity so model evaluation can carry more causal weight. If an admitted, decision-fit packet repeatedly produces poor proposals, the model and task design deserve scrutiny rather than another round of source blame.

Negotiate change before release

A contract is tested on ordinary days and valued on change days. The producer replaces a source, redefines a field, changes an aggregation window, adds late-arriving corrections or moves from event time to ingestion time. A registry entry that merely reports the new schema has not completed the job.

The release process should classify the change against every contract layer. Structural compatibility can be automated. Semantic and scope changes usually require named consumer acceptance. Temporal changes need replay against historical cases. Quality-threshold changes need an explicit reason and consequence analysis. Source changes need authority and reconciliation evidence.

Parallel running is often more informative than a blanket approval. The old and new products can feed the same contract suite over a bounded period. Differences are grouped by clause: missing records, changed grain, value deltas, temporal lag, source disagreement and downstream decision impact. The output is not “99.8 per cent match” without context. It identifies which propositions changed and whether the consumer accepts them.

Model canaries remain useful after this gate. They answer whether an admitted input distribution changes model behaviour. Data-contract canaries answer an earlier question: whether the new producer continues to assert the proposition the model was built to consume. The two tests should not be collapsed.

A practical release decision

The contract's depth should follow consequence, change rate, number of consumers, difficulty of correction and ambiguity of meaning. A static, low-consequence file does not need the same machinery as live account state used to authorise an irreversible action.

Use the following decision record before connecting a new source to model context:

• Name the entity, grain, population and decision purpose.
• Define material fields with units, scope and approved transformations.
• Declare valid, recorded, retrieved and decision-time semantics.
• Set quality and reconciliation thresholds with explicit failure dispositions.
• Identify producer, consumer, steward, authoritative source and replayable lineage.
• Classify breaking changes and require consumer acceptance before release.
• Generate a receipt that can reconstruct why each record crossed the boundary.
• Specify the fallback when the contract cannot establish admissibility.

The decisive release question is not “Can the model parse this source?” It is “Can the system defend what each admitted record meant at the moment of use?”

Where contracts stop helping

The strongest objection is practical. Contracts can become a second bureaucracy around the data platform. Producers fill templates, consumers approve versions, registries multiply and teams spend more time negotiating definitions than learning from data. Meanwhile robust models and outcome monitoring may handle ordinary variation cheaply.

That objection is correct under some conditions. Contract depth should earn its cost. A one-off analysis over a frozen, checksummed public dataset, with one author, one consumer, a deterministic transformation and no live decision, may need only a concise readme, schema, checksum and reproducible script. A full runtime registry, bitemporal history and multi-party approval process would add little fault-localisation value.

This is the negative control. Hold the dataset, semantics, owner and code fixed; remove source volatility, multiple consumers and consequential action. The elaborate contract loses much of its advantage. The result weakens any claim that every dataset deserves the same control stack. It supports the narrower claim that contracts become valuable as ambiguity, change, reuse and consequence increase.

A contract cannot certify reality

An authorised payroll source can still be wrong. A sensor can be calibrated badly. A human can enter a false value. The contract proves that declared checks passed, not that the represented world necessarily matches the record. Independent reconciliation, sampling, audit and postcondition verification remain necessary where consequence warrants them.

A contract also cannot settle a contested concept by naming it. “Vulnerable customer”, “suspicious activity”, “fair outcome” and “creditworthiness” involve legal, institutional and ethical judgement. A precise field definition may expose the dispute, which is useful, but it does not make one interpretation correct.

Nor does passing quality thresholds establish representativeness, causal relevance or fairness. A dataset can be complete relative to its source and systematically exclude a population. It can be fresh and still encode a biased process. The contract should record known limitations and population scope, while evaluation and governance test downstream consequences.

A contract detects only what it expresses

Validators are vulnerable to yesterday's imagination. Teams add a rule after an incident and assume the boundary is now safe. Novel changes can pass all known checks. Distribution monitoring, source comparison, failure injection and review of unexplained model behaviour remain necessary.

Easy-to-measure clauses can also crowd out difficult ones. A team may celebrate 100 per cent schema conformance while leaving “active customer”, “available balance” or “approved policy” undefined. A green contract can create false confidence when its tests cover representation but omit the proposition.

The remedy is not infinitely many rules. It is evidence discipline. Contract claims should state their boundary: “This receipt establishes that the record satisfied version 1.2.0 of the consumer's declared structural, semantic, temporal and provenance conditions at 10:00.” It should not say “the data is correct”.

Failure must remain recoverable

Blocking every uncertain record can create a different hazard. A rigid gate may stop essential operations during a source outage or reject legitimate edge cases. The contract therefore needs safe alternatives: bounded stale use for a permitted task, historical-only use, manual source verification, quarantine, human exception or suspension of the consequential action.

Ownership matters here. A platform team can run validators but cannot unilaterally decide that monthly net income is equivalent to annual gross income. Producers understand source generation. Consumers understand decision fitness. Domain stewards resolve definitions. Accountable decision owners accept residual risk. The contract makes this allocation visible; it does not replace it.

stateDiagram-v2
  [*] --> Claim
  state "Thought experiment one, the<br/>same double" as Claim
  state "Why compatibility stops early" as Test
  state "Why robustness cannot repair a<br/>hidden redefinition" as Revision
  Claim --> Test: expose mechanism
  Test --> Decision: evidence survives
  Test --> Revision: rival survives
  Revision --> Claim: narrow or rebuild
  Decision --> [*]

Compact glossary

Data contract

A producer-consumer agreement that makes structure, meaning, quality, time, authority, change and failure conditions testable.

Model contract

The interface and behavioural obligations governing how a model receives admitted inputs and produces bounded outputs.

Valid time

The time or interval in which a proposition holds in the represented world.

Transaction time

The time or interval in which a system stores or knows a particular assertion.

Contract receipt

A replayable record of contract version, checks, evidence references, failures and the resulting admissibility verdict.

Semantic break

A change in meaning, unit, grain, scope or authority that may occur without a structural incompatibility.

Make the input proposition defensible

A model can be evaluated only against the task and evidence it actually receives. When enterprise data arrives with unstable meaning, hidden scope or ambiguous time, model metrics combine at least two systems: the model and the upstream data estate. A good score can conceal a fortunate source state. A bad score can punish a model for a broken proposition.

The architecture therefore changes at the boundary. Sources no longer become model context merely because they are queryable or structurally compatible. They cross through a decision-specific contract that tests identity, grain, semantics, quality, time, provenance and authority. The gate emits a receipt and enforces a safe disposition. Only then does the model contract govern input representation, model behaviour, output constraints, abstention and escalation.

This ordering improves more than data quality. It improves fault attribution. A rejected source record is a source or contract event, not a mysterious model failure. A passed record that produces a poor proposal is now more credibly a model, task or decision-policy issue. Historical receipts support replay when definitions, sources or policies change.

The design must remain proportional. Frozen, low-consequence work can use a lean contract. Live, reused and consequential sources need stronger semantic, temporal and operating evidence. Contracts do not certify the world, settle contested concepts or guarantee fair outcomes. They make declared assumptions inspectable and enforceable before those assumptions become model behaviour.

The changed release rule is simple: establish the proposition before evaluating the prediction. A model contract without that upstream discipline governs the shape of an answer while leaving the meaning of its evidence unsecured. Data contracts come first because they make the later model contract worth having.