Stop asking.
Start listening.

{
  "id":        "evt_01J8ZQ4T",          // unique — enables dedupe
  "type":      "order.placed",        // past tense: it already happened
  "time":      "2026-07-02T09:14:03Z",
  "source":    "checkout-service",
  "subject":   "order/8842",
  "data": {
    "orderId":  "8842",
    "total":    129.90,
    "currency": "EUR"
  }
}

• Events are immutable. You never update an event; you publish a new one. OrderAmended follows OrderPlaced, and the log keeps both.
• Events are named in past tense. A command (PlaceOrder) asks for something. An event (OrderPlaced) reports that it happened. Mixing the two is the most common modeling mistake in the field.
• The producer doesn't know its consumers. That ignorance is the point. It's what lets teams ship independently, and it's also what makes tracing harder. Both are true.
• Carry enough state. A "thin" event (orderId only) forces consumers to call back for details, reintroducing coupling. A "fat" event carries the data consumers need. Most mature systems drift fat.

asyncapi: 3.0.0
info:
  title: Order events
  version: 1.2.0
channels:
  order.placed:
    messages:
      OrderPlaced:
        payload:
          type: object
          required: [id, type, time, data]
          properties:
            id:   { type: string }
            time: { type: string, format: date-time }
            data: { $ref: '#/components/schemas/Order' }

• Describe events like you describe APIs. AsyncAPI is OpenAPI's sibling for event channels: which topics exist, what messages they carry, what every field means. The spec becomes documentation, codegen input, and review artifact in one.
• Old events never go away. A consumer replaying a five-year-old stream will meet every schema version ever published. Evolution rules aren't bureaucracy. They're what makes replay possible at all.
• Enforce compatibility in CI, not in code review. A schema registry with compatibility checks rejects a breaking change at build time. Humans reviewing diffs miss what machines catch mechanically.
• Version the payload, not just the topic. Additive changes evolve a schema in place. Incompatible redesigns get a new major version, often a new topic (order.placed.v2) with both published during migration.

topic orders   // key = orderId → same order, same lane
├─ p0  #8842 #8842 #9011        consumer A
├─ p1  #7734 #7734 #7734 #8100  consumer A
├─ p2  #6621 #9455              consumer B
└─ p3  #5590 #5590              consumer B

group billing    // 2 consumers share 4 partitions
group analytics  // reads the same log, own offsets

rebalance: consumer B leaves →
  p2, p3 reassigned to A · processing pauses · resumes
  from committed offsets — duplicates possible, loss not

• Key by the invariant, not by convenience. Events for one order must stay ordered, so key on orderId. Key on customerId and one big customer becomes a hot partition, one lane jammed while the rest idle. The right key is the entity whose story must read in order.
• Partition count is a ceiling on parallelism. A consumer group can't usefully have more members than partitions, so the extras stand idle. Size partitions for peak, not average. Raising the count later reshuffles which keys land where.
• Rebalancing is routine, not failure. Deploys, crashes, and scale-out all trigger it. Well-behaved consumers commit offsets promptly, keep per-message work short, and tolerate the duplicates a rebalance can replay. Idempotency again.
• Cross-partition ordering doesn't exist, so design for it. If two entities' events must correlate in order, either they share a key or the consumer reorders with sequence numbers and a small buffer. Pretending the topic is globally ordered works right up to the first production load spike.