Skip to main content

Contract Versioning

Summary​

All 18 mapped lifecycle contracts are emitted with schema version 1. The common envelope supports a version field, but no lifecycle version-dispatch or compatibility governance was found.

Audience​

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

Reference Content​

Verified behavior​

  • Recruitment and Employee mappings explicitly assign version 1.
  • Notification reads a version from delivery metadata and otherwise assumes version 1.
  • Payroll and Leave use local structural parsing rather than version-specific handlers.
  • The raw outbox relay metadata builder does not include schema version; the serialized contract contains it.
  • No second version, deprecation attribute, compatibility test matrix or schema registry integration was found.

Evolution risks​

Renaming/removing structural fields can break consumer projections despite the unchanged version. Consumers tolerate some alternate field names, but that is transitional compatibility code, not formal evolution policy.

Backward/forward compatibility ownership, minimum supported version, rejection behavior, rollout order and contract retirement Require confirmation.

Requires confirmation​

Unless explicitly confirmed above, live delivery, consumer deployment, replay, reconciliation, retention, contract governance, monitoring and production ownership require confirmation.

Source References​

  • microservices/src/contracts/Events/IntegrationEvent.cs
  • microservices/src/recruitment-service/Infrastructure/RecruitmentDbContext.cs
  • microservices/src/employee-service/Infrastructure/EmployeeDbContext.cs
  • microservices/src/notification-service/Messaging/NotificationEventConsumer.cs

See Also​

Keywords​

  • Onboarding events
  • Offboarding events
  • Integration contracts

Revision Information​

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