---
title: "Wrap every event in one envelope · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/contracts-and-schemas/event-envelope
id: EVT-2
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1039
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Wrap every event in one envelope

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-2
- Level: Recommended
- Chapter: [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)
- Rule: Give every event the same outer fields, whatever its type. Use the CloudEvents attributes `id`, `source`, `type` and `specversion`, plus `time` and `dataschema`.
- Check: A contract test reads one message of each type from the test broker. Each has `id`, `source`, `type`, `specversion` and `time`, and no two messages share the same `source` and `id`.
- How: When each team invents its own wrapper, every consumer needs code per sender to find the ID and the type. CloudEvents 1.0 names four required attributes and binds them to HTTP, Kafka, AMQP and other transports. The pair of `source` and `id` is unique per event, so consumers use it to drop duplicates as [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) says. Put the business payload in `data`, and point `dataschema` at its versioned schema. Add a trace ID, so a message can be followed across services as [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing.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.

### JSON example

```json
{
  "specversion": "1.0",
  "id": "evt_7Hq2",
  "source": "https://shop.example.com/orders",
  "type": "com.example.shop.order.shipped.v2",
  "time": "2026-10-27T09:14:03Z",
  "dataschema": "https://shop.example.com/schemas/order-shipped/2.json",
  "datacontenttype": "application/json",
  "data": { "orderId": "ord_8f2k", "carrier": "postnord" }
}
```

### Python example

```python
import uuid
from datetime import datetime, timezone

def envelope(event_type: str, data: dict, schema_url: str) -> dict:
    return {
        "specversion": "1.0",
        "id": str(uuid.uuid4()),
        "source": "https://shop.example.com/orders",
        "type": event_type,
        "time": datetime.now(timezone.utc).isoformat(),
        "dataschema": schema_url,
        "datacontenttype": "application/json",
        "data": data,
    }
```

### JavaScript example

```js
import { randomUUID } from 'node:crypto';

export const envelope = (type, data, schemaUrl) => ({
  specversion: '1.0',
  id: randomUUID(),
  source: 'https://shop.example.com/orders',
  type,
  time: new Date().toISOString(),
  dataschema: schemaUrl,
  datacontenttype: 'application/json',
  data,
});
```

## Sources

- [CloudEvents specification 1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md)

## Related rules

- EVT-11 [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) in Integration and events
- OPS-15 [Trace requests across services](https://agentwranglers.se/playbook/operations/metrics-and-traces/distributed-tracing.md) in Operations and observability

**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/event-envelope">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Describe every channel in an AsyncAPI document](https://agentwranglers.se/playbook/events/contracts-and-schemas/asyncapi-contracts.md)
- Next: [Version event payloads](https://agentwranglers.se/playbook/events/contracts-and-schemas/event-versions.md)
- [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)