> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and compatibility

> How Events V1 evolves without breaking existing webhook consumers.

The final segment of every event type is its major version:

```text theme={null}
order.created.v1
```

Events V1 evolves additively. Consumers must ignore object properties they do
not recognize and safely handle unfamiliar descriptive enum values. Producers
validate every event against its schema before publishing it.

## Compatible V1 changes

* Adding an optional field.
* Adding an optional object property.
* Adding a new descriptive enum value when consumers can safely ignore it.
* Adding a new public event topic.
* Adding examples, clarifications, or non-semantic schema annotations.

## Breaking changes

These require a new event major version rather than a silent V1 change:

* Removing a field.
* Making an optional field required.
* Changing a field's type or meaning.
* Narrowing accepted values in a way that invalidates existing consumers.
* Renaming an event topic or changing its resource subject semantics.

## Resource versions and replays

`resourceversion` belongs to the event envelope because it represents the
resource projection after the fact. It is not a delivery sequence number.
Consumers should persist the greatest applied version per resource and reject
older state updates. Always deduplicate first by CloudEvent `id`.

An operator or the Developer Dashboard may replay a delivery. Replays preserve
the immutable CloudEvent ID and payload; delivery-attempt metadata can differ.
Your handler must therefore treat every successful `id` as idempotent.

## Schema and documentation locations

* Live public AsyncAPI: `https://api.batchrelay.com/asyncapi.json`
* Per-event schema: the CloudEvent `dataschema` URL
* Public documentation snapshot:
  [`/specs/events-v1.asyncapi.json`](/specs/events-v1.asyncapi.json)

The live API owns the contract. Documentation pages and the checked-in snapshot
are release artifacts and must be updated from the same public AsyncAPI source.