Event API Specification: [Event domain or application name]

Complete specification for an event-driven, asynchronous interface: brokers, channels, operations, messages and schemas, envelope, ordering, delivery guarantees, retries and dead-letter handling, schema evolution, security and consumer onboarding. The structure follows the concepts of the AsyncAPI Specification 3.0 (servers, channels, operations, messages, components) and uses the CloudEvents 1.0 envelope. Replace every [bracketed] value and every row marked Example. Worked examples use an order-fulfilment event stream.

Document control

Approvals

Revision history

Contents

1. Introduction
2. Servers and brokers
3. Channels
4. Operations
5. Messages and schemas
6. Ordering and partitioning
7. Delivery semantics
8. Retries and dead-letter handling
9. Schema evolution and compatibility
10. Security
11. AsyncAPI document
12. Interaction flows
13. Operations and service levels
14. Consumer onboarding
15. Glossary and references

1. Introduction

1.1 Purpose

[What the events communicate and why an asynchronous interface was chosen. Example: "The Fulfilment service publishes the lifecycle of each shipment so that billing, notifications and analytics can react without calling Fulfilment synchronously."]

1.2 Scope and context

1.3 Event design principles

• Events describe facts that already happened, named in the past tense.
• Each event type has exactly one producing application.
• Payloads carry enough state for typical consumers to act without a call-back; sensitive data is excluded unless listed in section 10.
• Consumers must tolerate duplicates, gaps in optional fields and unknown fields.

2. Servers and brokers

3. Channels

Channel naming convention: <domain>.<entity>[-<qualifier>].v<major>, lower case, dot-separated. A new major version means a new channel.

4. Operations

5. Messages and schemas

5.1 Envelope: CloudEvents attributes

All messages use the CloudEvents 1.0 envelope in binary content mode: attributes travel as protocol headers (prefixed ce_ on Kafka) and the payload is the message body. Examples in this document use the structured JSON form for readability. partitionkey comes from the CloudEvents partitioning extension.

5.2 Message catalogue

5.3 Example: ShipmentDispatched

Payload fields:

{
  "specversion": "1.0",
  "id": "01HV7A0B2C9D8E7F6G5H4J3K2L",
  "source": "/fulfilment-service/eu-west-1",
  "type": "com.example.fulfilment.shipment.dispatched.v1",
  "time": "2026-03-15T14:02:11Z",
  "subject": "shp_01HV79ZZ0K",
  "datacontenttype": "application/json",
  "dataschema": "https://schemas.example.com/fulfilment/shipment-dispatched/3",
  "partitionkey": "ord_01HV6Z3K8Q",
  "data": {
    "shipmentId": "shp_01HV79ZZ0K",
    "orderId": "ord_01HV6Z3K8Q",
    "carrier": "LA_POSTE",
    "trackingNumber": "6A12345678901",
    "dispatchedAt": "2026-03-15T14:02:11Z",
    "parcelCount": 1,
    "estimatedDeliveryDate": "2026-03-17"
  }
}

5.4 Example: [Message name]

[Repeat the field table and a complete example for every message in 5.2.]

6. Ordering and partitioning

The partition for a key is chosen by hashing:

so increasing the partition count $P$ remaps keys and can break ordering during the change.

7. Delivery semantics

7.1 Producer guarantees

• Delivery: at least once. Duplicates are possible after producer retries or failover.
• No silent loss: events are written to a transactional outbox table in the same database transaction as the state change, and a relay publishes them with broker acknowledgement from all in-sync replicas (acks=all).
• Producer idempotence is enabled to reduce, not eliminate, duplicates.
• Maximum publish delay from state change to broker: [5 s at p99].

7.2 Consumer obligations

7.3 Exactly-once statements

[State whether any end-to-end exactly-once processing is offered. Example: "Not offered. Consumers achieve effectively-once results through idempotent processing as described in 7.2."]

8. Retries and dead-letter handling

Dead-letter messages carry the original headers plus dlq_reason, dlq_consumer, dlq_attempts and dlq_first_failure_time.

9. Schema evolution and compatibility

9.1 Compatibility mode

The schema registry enforces [BACKWARD_TRANSITIVE / FULL_TRANSITIVE] compatibility for every subject in this specification: a consumer using any newer schema can read all data written with older schemas.

9.2 Breaking changes

A breaking change creates a new major event type (for example com.example.fulfilment.shipment.dispatched.v2) on a new channel. The producer dual-publishes v1 and v2 for at least [6 months]; v1 is then sunset after every registered consumer confirms migration.

9.3 Deprecation of fields

Mark deprecated fields with "deprecated": true in the schema doc string, announce in the changelog, keep populating them for [3 months], then remove only if the compatibility mode allows it.

10. Security

11. AsyncAPI document

The authoritative machine-readable contract is [asyncapi/fulfilment.yaml]. The skeleton shows the AsyncAPI 3.0 structure used here.

asyncapi: 3.0.0
info:
  title: Fulfilment Events
  version: 1.2.0
  description: Shipment lifecycle events published by fulfilment-service.
defaultContentType: application/json
servers:
  prod:
    host: broker-1.prod.example.com:9093
    protocol: kafka
    security:
      - $ref: '#/components/securitySchemes/oauth'
channels:
  shipment:
    address: fulfilment.shipment.v1
    messages:
      shipmentDispatched:
        $ref: '#/components/messages/ShipmentDispatched'
operations:
  publishShipmentDispatched:
    action: send
    channel:
      $ref: '#/channels/shipment'
    messages:
      - $ref: '#/channels/shipment/messages/shipmentDispatched'
components:
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth2/token
          availableScopes:
            events:fulfilment:read: Read fulfilment events
  messages:
    ShipmentDispatched:
      name: ShipmentDispatched
      contentType: application/json
      headers:
        type: object
        properties:
          ce_id: {type: string}
          ce_type: {type: string, const: com.example.fulfilment.shipment.dispatched.v1}
          ce_time: {type: string, format: date-time}
      payload:
        $ref: '#/components/schemas/ShipmentDispatchedPayload'
      bindings:
        kafka:
          key:
            type: string
            description: orderId
  schemas:
    ShipmentDispatchedPayload:
      type: object
      required: [shipmentId, orderId, carrier, trackingNumber, dispatchedAt, parcelCount]
      properties:
        shipmentId: {type: string}
        orderId: {type: string}
        carrier: {type: string}
        trackingNumber: {type: string}
        dispatchedAt: {type: string, format: date-time}
        parcelCount: {type: integer, minimum: 1}
        estimatedDeliveryDate: {type: string, format: date}

12. Interaction flows

The main flow from a carrier scan to downstream reactions, including the outbox relay and a consumer failure routed to the dead-letter channel:

13. Operations and service levels

Replay: consumers may reset offsets within the retention window. Requests to re-publish older history go to [@team-fulfilment] with [5 business days] notice.

14. Consumer onboarding

Registered consumers:

15. Glossary and references

15.1 Glossary

15.2 References

Standard and licence note

Structure aligned with the AsyncAPI Specification 3.0 (Apache License 2.0): servers, channels, operations, messages and reusable components, with the CloudEvents 1.0 envelope (CNCF, Apache License 2.0). Based on common industry practice for event-driven integration, including the transactional outbox and dead-letter channels. This template is original text written for this collection and reproduces no text from those specifications; read them for their normative requirements. Template licence: MIT.