Skip to main content
The final segment of every event type is its major version:
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
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.