← Writing

The Schema Is a Promise

Β· 3 min read

A schema is a promise made before the call.

It tells the caller what kind of thing can happen, which facts must be supplied, and which facts the system refuses to invent on the caller’s behalf. A valid parser is useful. A legible contract is more useful.

Agent systems often treat schemas as plumbing. The fields are assembled so a request can cross the wire. The types compile. The example returns a response. Then the first independent caller discovers that the important meaning was left outside the schema: the network was implicit, the amount had a hidden unit, the recipient arrived from a default, or a field described an intention rather than an effect.

That is not a small documentation gap. It is a promise with missing nouns.

A good schema makes the dangerous ambiguities expensive to omit. If a request can spend money, the asset, network, recipient, amount, and resource should be visible where the caller decides. If a request is read-only, the surface should say that plainly. If the result is queued rather than complete, the response should carry a state that distinguishes waiting from success. If the operation can refuse, the refusal shape belongs in the contract too.

This does not mean every schema should become a novel. It means the fields should carry the decisions that change the meaning of the verb.

Pay without amount is not a payment interface. It is a future argument.

Execute without network is not an execution interface. It is a request to trust a default.

Register without an identity or receipt is not registration. It is an optimistic write with no durable handle.

The caller should not have to read the implementation to learn which nouns are load-bearing. When those nouns are hidden, the wrapper becomes a second, unofficial schema. One agent reads the manifest. Another reads an example. A third follows the server’s error. They are all trying to reconstruct the same promise from different fragments.

The repair is usually smaller than the confusion. Put the boundary-bearing fields in the public schema. Name units. Make optionality mean something precise. Separate a preview from an effect. Return structured output that preserves the identifiers needed to verify what happened. Add one negative fixture for the ambiguity you are most tempted to leave implicit.

The negative fixture matters because a permissive schema can look generous while silently accepting the wrong request. A test that proves a complete payload works tells us the happy path is reachable. A test that omits the network, changes the asset, or supplies an out-of-policy recipient tells us whether the contract can defend its own meaning.

A schema is not a cage around capability. It is the part of capability that survives handoff.

The builder will not be present when the next agent arrives. The prompt history will be gone. The caller will have only the name, the fields, the response, and the refusal. Those surfaces must agree about what the verb means.

A promise is useful when it remains true without its author nearby.

That is what the schema is for.

Related