Describe what the caller must supply
An input schema should express the shape you actually accept, including required values and constraints that can be checked before execution. Keep the distinction between an absent value and a valid empty value clear.
OperationSpec separates the main input from optional transport-related parameter, query and header models. Inspect the adapter's mapping before assuming a field is read from a particular part of a request.
Describe what the caller may rely on
The output model tells callers what a successful handler must return. Use a stable shape that reflects the product outcome rather than leaking the entire response from a provider.
Output validation detects a mismatch after the handler returns. It helps identify a broken boundary, but the host still owns the transaction or recovery behavior of effects that have already happened.
Give expected failures names
The model supports typed success and failure catalogs as well as compatibility error declarations. Use expected failures to describe product cases that a caller can handle, such as unavailable resources or a rejected transition.
The registry's executeResult path carries a canonical result and normalizes failures with operation and trace context. Adapters project that result into their own protocol. Avoid making clients inspect an incidental human error string as their primary control flow.
| Kind of outcome | Caller concern | Where to investigate |
|---|---|---|
| Invalid request | Correct the submitted data | Input schema and mapping |
| Expected business failure | Choose another valid product action | Declared result and handler |
| Denied execution | Satisfy an authorized policy or approval path | Host decision context |
| Invalid handler output | Report or repair an implementation defect | Handler and output model |
Use examples as boundary fixtures
Keep a representative input and result near the operation and use them in the guide and the test. Include one failure case that demonstrates the reason the constraint exists.
When you change a required field or named outcome, review clients and docs together. Matching TypeScript imports alone does not show whether a deployed caller still sends the old wire shape.