Skip to main content

Notification Event Versioning

Summary​

A schema version travels with every event, but nothing reads it. No handler, resolver case or parser branches on version, so event versioning is carried rather than implemented.

Audience​

Engineers, architects, QA, support and implementation partners.

Reference Content​

The verified reference material for this topic is set out in the sections below.

Where the version lives​

LayerVerified behavior
Shared contract baseDeclares a schema version field on every integration event
PublisherWrites the contract's schema version into the metadata and therefore a header
ConsumerParses the header to an integer, defaulting to 1 when absent or unparseable
EnvelopeCarries the parsed value as a field
Downstream logicNever reads it
Test publish hookHard-codes the value 1 and does not accept a caller override

The value is present at every layer and consumed by none.

Verified absence​

  • No version comparison, switch or conditional anywhere in the service.
  • No versioned contract type, no suffix convention and no parallel handler for a second version.
  • No minimum or maximum supported version check, and no rejection of an unrecognised version.
  • No upcasting, downcasting or migration of an older payload shape.
  • No version recorded in persistence — neither the message nor the idempotency ledger stores the event schema version.
  • No version negotiation, capability advertisement or compatibility header.

Consequence​

Because parsing is tolerant, a version-2 payload with a renamed or removed field deserializes successfully and produces empty template variables rather than an error. The notification is still created and delivered, with blanks where the data should be.

A publisher can therefore make a breaking payload change and see no failure signal from Notification. The failure is silent and appears as degraded message content.

The default-to-1 behavior compounds this: a message with a malformed or missing version header is indistinguishable from a genuine version 1.

Routing-key versioning​

There is none. Routing keys are flat event-type strings with no version segment, so a versioned event type would need a new binding and a new resolver case — effectively a new event rather than a new version of an existing one.

Distinction from other version concepts​

Two other version fields exist in the module and neither is an event schema version: the template version on the template table, and the persisted template version copied onto each message. Both describe notification content, not event contracts.

Classification​

Foundation — the field is plumbed end to end; no versioning behavior exists.

Requires confirmation​

Whether version-aware handling is planned, and how breaking payload changes are intended to be coordinated across publishers, require confirmation.

See Also​

Keywords​

  • Notification database
  • Versioning
  • Draft database documentation

Source References​

  • microservices/src/notification-service/Messaging/NotificationEventEnvelope.cs
  • microservices/src/notification-service/Messaging/NotificationEventConsumer.cs
  • microservices/src/contracts/Events/IntegrationEvent.cs
  • microservices/src/shared-kernel/Messaging/RabbitMqEventBus.cs
  • microservices/src/notification-service/Api/NotificationEndpoints.cs

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-21
  • Review cycle: Quarterly