Typed contracts for AI workflows: structured outputs aren't enough

The JSON was valid. The payment wasn't.

A manufacturer's supplier-rebate workflow reads a signed agreement, extracts the rebate terms, checks eligibility, routes unusual cases for approval and tells the payment system to issue the credit.

The agreement allows up to $125,000 in rebates for 2026, including credits already paid. The supplier has received $80,000, so at most $45,000 is still due.

A model reads the agreement and returns:

{ "supplierId": "S-2291", "amount": 125000, "currency": "USD", "period": "2026" }

It's valid. The supplier exists, the currency is allowed, the amount is positive, the period is recognized. The next step has an input called amount too, and it reads it as the amount to pay now. A visual mapping joins amount to amount. The policy check confirms it's within the $125,000 annual cap. A manager sees "within contractual limit" and approves. The payment API pays $125,000 and returns success. The supplier's total for the year is now $205,000.

The number had a type: number. What it didn't carry was its meaning. One step produced an annual entitlement. The next consumed an amount payable now.

Why do AI workflows break at the boundaries between steps?

Because information crosses more kinds of boundaries, and many of them can change meaning: model to validator, query to context, approval to resume, proposal to API. Loose JSON and naming conventions let meaning slip at each one.

Distributed systems always needed interface contracts. AI applications need them more. A rule returns a value from code. A model generates a value from context. A query returns a point-in-time view. An approval binds to a rendered summary. An event resumes a paused case later. A tool adapter turns a proposal into an irreversible action.

Ambiguity creeps in through fields that look alike but mean different things; numbers without units, currency, basis or effective date; optional fields with silent defaults; enum values that drift between systems; IDs missing tenant or legal-entity scope; model output that's well formed but unsupported by evidence; structured facts flattened into prose and re-parsed; errors as free-text strings; and running cases resuming against newer schemas.

When these surface downstream, they get called hallucinations or integration bugs. Often the real cause is that nobody defined what was allowed to cross the boundary.

"Between every step" means every boundary where ownership, trust, time, state, policy or side effects change, not every private function call. A contract can use JSON Schema, an OpenAPI description, an event envelope, a database schema or a domain validator. What matters is that it exists, is versioned and is enforced.

Is schema validation enough?

No. A payload can pass structural validation and still fail on meaning, evidence, authority, state or side-effect safety. These are six different questions, and each needs its own check.

OWASP separates syntactic from semantic validation and recommends validating untrusted data as early as possible. Model output is untrusted data: well formed, and possibly wrong, unsafe or wrong for the next step.

What a useful contract carries

A contract can be compact, but it has to stop the receiver from guessing. Eight dimensions recur:

A shallow contract says amount is a number. A stronger one carries the proposition:

{
  "status": "PROPOSED",
  "remainingRebate": { "value": 45000, "currency": "USD", "basis": "incremental_payable",
                       "period": "2026", "derivedFrom": ["annualCap", "priorCredits"] },
  "evidence": [{ "doc": "agreement-7781", "clause": "4.2" }],
  "scope": { "tenant": "eu-mfg", "legalEntity": "DE-01" }
}

That's an illustration, not a standard. The point is the difference between passing a number and passing something the next step can evaluate without inventing context.

Proposal isn't fact: put status in the type

A model's output shouldn't gain the authority of a verified system fact just because both are JSON. Treat status as part of the type, moving through stages such as proposed, structurally valid, domain valid, evidence supported, authorized, approved and committed. Not every workflow needs every stage. What matters is that consequential transitions are explicit.

A payment step shouldn't accept a proposed payment instruction, only an authorized or approved one, depending on policy. A review step binds its decision to the exact proposal, evidence, schema and mapping version shown. If anything material changes, the old approval doesn't cover the new payload (see human-in-the-loop approval).

This is the line between probabilistic and deterministic work in practice: the model's output stops at a typed checkpoint before anything consequential happens (more in deterministic vs probabilistic AI steps).

Every kind of step needs its own contract

OpenAPI, CloudEvents and Problem Details for HTTP APIs are good foundations here, because success, failure, identity and version shouldn't be reconstructed from free-text strings.

Mappings are part of the contract

Many failures happen on the edge between steps, not inside them. A governed mapping shows which producer field feeds each consumer field; whether units, scale, precision, time zone or ID namespace change; how enums translate and what happens to unknown values; whether missing values are rejected, defaulted or sent for review; what's dropped, redacted or flattened into prose; which scope and provenance survive; and which mapping version a running case used.

A default isn't a convenience. It's a business decision made without evidence. A unit conversion changes what a number means. An enum fallback to OTHER can erase exactly the distinction that should trigger review. Never infer compatibility from matching field names.

Structured output is formatting, not proof

Schema-constrained generation cuts parser failures and makes validation easier. It doesn't prove the values are correct, supported, authorized or safe. A perfectly valid object can contain an invented customer ID, a real account outside the user's scope, an amount from the wrong document, a date in the wrong time zone, or tool arguments that satisfy the schema and break policy. OWASP lists improper output handling among the top LLM risks for exactly this reason.

So the workflow needs typed non-success outcomes: abstained (with what's missing), invalid structure, domain invalid, out of scope, policy denied, needs review, and uncertain side effect. These stop the next step reading silence, null, a timeout or free text as success, and they give clear routes: reject, repair, fetch more evidence, try another step, escalate, reconcile or stop.

Changing a contract is more than staying parseable

Bind contract and mapping versions to each published workflow version, and check at publication for unmapped required fields, narrowed enums, unsafe defaults, missing failure routes and illegal status transitions. Running cases stay on the contracts they started with unless they're migrated deliberately. Record which contract and mapping each step used, what passed and failed, and what the approver saw, so incidents and replays can be reconstructed exactly.

Common anti-patterns

Ten rules for typed AI workflows

1. Put contracts on consequential boundaries, not just internal functions.
2. Make units, basis, time, identifiers and status explicit.
3. Treat model output as a proposal until it's validated.
4. Validate at every trust or ownership boundary.
5. Treat mappings, conversions and defaults as governed artifacts.
6. Make failure, abstention, denial and uncertain effects typed outcomes.
7. Bind contract and mapping versions to the published workflow and each running case.
8. Bind approval to the exact typed proposal and evidence reviewed.
9. Check semantic compatibility before publishing a change.
10. Record contract versions, validation results and transitions for every case.

The result: uncertainty ends at a contract

Attention in enterprise AI usually goes to what's inside each step: the model, the rules, the retrieval, the API, the reviewer. Many of the hardest failures happen between them, where meaning, authority, state and evidence get translated or quietly lost.

Typed contracts make those edges part of the design. The contract states what may cross. The mapping states how it changes. Validation decides whether the next step may use it. The record shows what actually happened. The goal isn't to make models behave deterministically. It's to make sure their uncertainty stops at an explicit, inspectable contract before it becomes an enterprise obligation.