Skip to main content

Leave Event Contract Versioning

Summary​

All six Leave mappings currently emit schema version 1 through shared contract records; no formal schema registry is implemented.

Audience​

Contract owners, producers, consumers, QA, architects, and release reviewers.

Concept​

IntegrationEvent standardizes event identity/type/time, optional correlation and causation, optional cross-service tenant/user context, source service, and SchemaVersion. Leave-specific records extend that envelope with lifecycle categories. Contract ownership is shared source code, while Leave Service owns correct production and each consumer owns tolerant processing.

Current mappings hard-code version 1. The serialized payload contains SchemaVersion. The outbox relay publishes stored JSON and builds selected metadata; consumers also apply a version fallback when broker metadata omits it. No compatibility matrix, generated schema registry, formal consumer capability registry, or automated version negotiation was found.

Recommended governance based on the current contract model:

  • Treat new optional fields as additive only after producer/consumer serialization tests.
  • Avoid removing, renaming, changing meaning/type, or making an optional field required within the same version.
  • Use a new version and coordinated migration for breaking semantic or structural changes.
  • Require Payroll and Notification review for their subscribed decisions.
  • Preserve Foundation contracts such as LeaveEncashed without implying runtime availability.
  • Verify old payload tolerance, missing-field defaults, and unknown-field behavior before release.

These are change-review expectations, not proof of an implemented registry.

Source References​

  • microservices/src/contracts/Events/IntegrationEvent.cs
  • microservices/src/contracts/Events/LeaveLifecycleEvents.cs
  • microservices/src/leave-service/Infrastructure/LeaveDbContext.cs
  • microservices/src/shared-kernel/Outbox/IntegrationEventJsonSerializer.cs
  • microservices/src/payroll-service/Messaging/PayrollReadModelConsumer.cs
  • microservices/src/notification-service/Messaging/NotificationEventConsumer.cs

See Also​

Keywords​

  • SchemaVersion
  • Backward compatibility
  • Contract governance

Revision Information​

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