Contract standards
The rules Acme teams follow when defining, versioning and changing commands, events and queries.
Commands, events and queries are the public language between Acme systems. A contract is not ready until it is understandable by a team that does not own the implementation.
Contract types
| Type | Meaning | Example |
|---|---|---|
| Command | A request for an owner to do work. | Reserve InventoryReserve InventoryCommandv1.0.0Command to reserve stock for the items in a checked-out cart. Ownerordering-platformSchemaMapView docs, Authorize PaymentAuthorize PaymentCommandv1.0.0Command to authorize payment for the total of a checked-out cart. Ownerordering-platformSchemaMapView docs, Create OrderCreate OrderCommandv1.0.0Command to create a new order from a checked-out cart. Ownerordering-platformSchemaMapView docs |
| Event | A fact that already happened. | Order CreatedOrder CreatedEventv1.0.0Published when a new order has been created. Ownerordering-platformSchemaMapView docs, Payment SucceededPayment SucceededEventv1.0.0Published by Stripe when a charge succeeds. Ownerpayments-platformSchemaMapView docs, Inventory ReservedInventory ReservedEventv1.0.0Published when stock has been successfully reserved for an order. Ownerfulfilment-platformSchemaMapView docs |
| Query | A read contract owned by one capability. | Get OrderGet OrderQueryv1.0.0Query to fetch a single order by its identifier. Ownerordering-platformSchemaMapView docs, Search ProductsSearch ProductsQueryv1.0.0Query to search the catalog for products matching a term, with optional filters and pagination. Ownersearch-platformSchemaMapView docs, Get Product ReviewsGet Product ReviewsQueryv1.0.0Query to fetch the published reviews and aggregate rating for a product. Ownerreviews-platformSchemaMapView docs |
Required fields
Every contract page should document:
- business purpose,
- producer or handler,
- consumers where known,
- schema or payload reference,
- version and compatibility policy,
- failure semantics for commands and queries,
- replay and ordering assumptions for events.
Versioning rules
Additive fields are allowed when consumers can ignore them. Removing fields, changing meaning, tightening validation or changing delivery semantics is breaking and requires a new version or a migration plan.
Use deprecation before removal. Keep the old contract documented until all consumers have moved.
Review checklist
Before changing a contract, teams must identify all known consumers, confirm whether the change is additive or breaking, update flow pages that depend on the contract, and add an ADR when the change introduces a new integration pattern.
Review a proposed command, event or query contract change for Acme Inc. Decide whether it is additive or breaking, list
known consumer risks, identify missing schema or payload details, and suggest a migration plan if the change is not
backward compatible. Include the catalog pages that need updates.Review a proposed command, event or query contract change for Acme Inc. Decide whether it is additive or breaking, list known consumer risks, identify missing schema or payload details, and suggest a migration plan if the change is not backward compatible. Include the catalog pages that need updates.