Agent WranglersContracts and schemas
Describe every channel in a contract and wrap each event in one envelope. Let a registry refuse changes that break the services that read them.
- Required 1
- Recommended 4
Required
Let a schema registry refuse breaking changes
EVT-4Register every event schema in a schema registry with a compatibility mode, and let it refuse a new version that breaks the readers. Upgrade readers or writers first, in the order that mode demands.
Recommended
Describe every channel in an AsyncAPI document
EVT-1Keep one AsyncAPI document per service in the repository. It lists every channel the service sends to or receives from, and the schema of each message.
Wrap every event in one envelope
EVT-2Give every event the same outer fields, whatever its type. Use the CloudEvents attributes
id,source,typeandspecversion, plustimeanddataschema.Version event payloads
EVT-3Name each event type and version its payload, and change it only by adding fields, as with the API itself.
Treat each source schema as a contract
EVT-5Write down the columns and types the pipeline reads from each source. Stop the load and alert the owner when a source drops, renames or retypes one of them.
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/events/contracts-and-schemas">Agent Wranglers integration and events playbook</a>. In code you write, add a comment next to it with the same link.