AI interfaces

Structured output is a contract

A model that returns almost-JSON is not integrated. It is freelancing inside your parser.

~5 minAI
scroll
01 · the shape

Text is a terrible API boundary

Free-form text is great for humans and slippery for code. The moment another service depends on the shape, the answer needs a schema, validation, retries, and a failure path.

parser · almost works

The useful signal is usually already there.

guardrails armed

Hit the button and watch the hidden AI surface area light up.

02 · the move

Make the shape explicit

Define the fields, allowed values, and nullable cases before calling the model. Then validate the response like any other external dependency.

schemas/triage.json

A schema turns vibes into a contract your app can reject.

03 · the check

Reject invalid answers loudly

If the model misses the schema, do not patch around it downstream. Retry with the validation error, fall back to a human path, or fail the job with a useful log.

AI launch switchboard
sloppy
shippable0
fragile: the model is still freelancing without enough checks

Flip the switches and watch the story turn into a tiny operating model.

0allowed priority values beats free text
0schema shared by prompt and validator
0silent parser fallbacks
04 · the takeaway

Reliable AI feels boring at the boundary

The inside can be probabilistic. The edge of the system should look like software: typed, validated, observable, and honest when it cannot comply.

source trail