---
title: "Describe every channel in an AsyncAPI · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/contracts-and-schemas/asyncapi-contracts
id: EVT-1
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1024
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Describe every channel in an AsyncAPI document

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-1
- Level: Recommended
- Chapter: [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)
- Rule: Keep 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.
- Check: CI validates each AsyncAPI document and fails on any error. A script lists the topics or queues each service uses in code, and every one appears as a channel in that service's document.
- How: An event without a written contract is a promise nobody can check. AsyncAPI 3.1 describes channels, the `send` and `receive` operations on them, and each message's payload schema, in YAML or JSON. Write payloads as JSON Schema, Avro or Protobuf, and reuse them from `components`. Generate docs and test fixtures from the document, and validate it in CI. Webhooks that a public API sends can live in OpenAPI's `webhooks` section instead, as [Version event payloads](https://agentwranglers.se/playbook/events/contracts-and-schemas/event-versions.md) says. Each consumer tests against the document as [Check the contract between services](https://agentwranglers.se/playbook/testing/integration-and-contract-tests/contract-tests.md) describes.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
asyncapi: 3.1.0
info:
  title: Example Shop orders
  version: 2.4.0
channels:
  orderShipped:
    address: shop.orders.shipped
    messages:
      orderShipped:
        $ref: '#/components/messages/orderShipped'
operations:
  sendOrderShipped:
    action: send
    channel:
      $ref: '#/channels/orderShipped'
components:
  messages:
    orderShipped:
      payload:
        type: object
        required: [orderId, shippedAt]
        properties:
          orderId: { type: string }
          shippedAt: { type: string, format: date-time }
```

### JavaScript example

```js
import { Parser } from '@asyncapi/parser';
import { readFile } from 'node:fs/promises';

const { diagnostics } = await new Parser().parse(await readFile('asyncapi.yaml', 'utf8'));
const errors = diagnostics.filter(d => d.severity === 0);
if (errors.length) throw new Error(errors.map(d => d.message).join('\n'));
```

### Python example

```python
import subprocess

def validate_asyncapi(path: str) -> None:
    subprocess.run(["asyncapi", "validate", path], check=True)
```

## Sources

- [AsyncAPI Specification 3.1.0](https://www.asyncapi.com/docs/reference/specification/v3.1.0)

## Related rules

- EVT-3 [Version event payloads](https://agentwranglers.se/playbook/events/contracts-and-schemas/event-versions.md) in Integration and events
- TST-14 [Check the contract between services](https://agentwranglers.se/playbook/testing/integration-and-contract-tests/contract-tests.md) in Testing
- EVT-4 [Let a schema registry refuse breaking changes](https://agentwranglers.se/playbook/events/contracts-and-schemas/schema-compatibility.md) in Integration and events

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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/asyncapi-contracts">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Next: [Wrap every event in one envelope](https://agentwranglers.se/playbook/events/contracts-and-schemas/event-envelope.md)
- [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)