Specify the operation, not just the JSON
A JSON schema can require a supplier identifier and a monetary total. It cannot, by itself, establish that the supplier belongs to the current workspace, that the currency is permitted or that the caller can create a bill. A task contract separates data shape from semantic requirements, access policy and action scope.
For an invoice draft, the contract should name the source documents, accepted reference records, destination mapping and permitted operation. Creating a draft must not imply posting an accounting entry, approving an invoice or initiating a payment. Each additional effect requires its own explicit authorization and completion criteria.
Pin the meaning of each run
Version the contract alongside its input and output schemas, verifier definitions and destination mapping. Record the versions selected when a run is accepted. Updating a supplier-match rule during a retry should not silently change the meaning of an already accepted task. A deliberate re-evaluation can create a new run with a visible relationship to the earlier one.
External business data can change even when configuration remains pinned. The evidence should therefore identify the purchase order or catalog snapshot used by each check, including an observed version when the source supports one. Before writing, recheck conditions whose validity depends on current state.
| Contract element | Example question it answers |
|---|---|
| Input schema | Which document and source identifiers are required? |
| Semantic rules | Which supplier and purchase-order relationships are valid? |
| Action boundary | Can this run create a draft, or only propose one? |
| Completion evidence | Which persisted fields must match the checked candidate? |
Review the contract with its failure cases
A useful acceptance set includes a valid example, a missing required field, conflicting references, a duplicate business document and a destination timeout. Decide in advance which cases fail, which request a review and which can be retried safely. This gives engineering and operations a common definition of done.
Keep the first contract small enough that its checks can be explained. Free-form instructions may supplement a contract, but should not expand its write permissions or replace its verifiers. Review changes to the contract as changes to business behavior, with clear ownership and an acceptance set that can be run again.
Missing a detail or found a problem?
Send a documentation question →