Capability Contracts
Contracts that describe an allowed business action—its authority, conditions, outcomes and effects—not merely the JSON it accepts.
A payload schema can tell a caller that resolution_category is required and that an evidence list must be an array. It cannot, on its own, tell the caller whether the actor may request resolution, whether a regulatory hold prevents it or whether the system will re-check the issue before deciding.
Those are behavioural facts. A capability contract makes them part of the public interface.
What a useful contract says
A governed capability needs to describe the intent it accepts, the operational authority that owns the decision, the permissions or delegation it requires, the conditions it will test and the evidence it expects. It must also describe the possible outcomes: a successful result, defined rejection reasons, side effects, audit expectations and events.
The contract does not remove the need for implementation. It makes the implementation’s public promise explicit enough for a user interface, integration or agent to behave responsibly. A caller can discover that a request is idempotent, that current state will be re-read and that a particular rejection is retryable only after it obtains more evidence.
More than a type definition
Typed fields remain important. They prevent a caller from constructing malformed input and make generated clients possible. But a schema concerned only with data shape leaves the difficult part of an enterprise action unspecified. The capability contract joins data shape to authority and consequence.
That is particularly important for agents. An agent can infer an intention from language and context, but it should not have to infer hidden business rules from examples, prompt text or the behaviour of a UI. The contract gives it a defined surface: this is the action, these are the conditions, and these are the outcomes the system may return.
The machine-readable form of this model is being developed separately. Until it is released, this reference deliberately stays at the architectural level rather than presenting a draft format as a completed standard.
The contract’s value depends on the same rule that underpins the whole model: consumers propose; systems decide .